AI Agents API

The Agents API is the surface designed for AI agents, trading bots, and automated systems to read MAGMA state and act on it programmatically. It pairs a stable, machine-friendly narrative feed with an API-key auth model and an endpoint for autonomous oracle resolution.

Prefix: /v1/agent. Base host: https://api.magmaprotocol.xyz.

Two ways for machines to read MAGMA

The product REST reference is fully usable by automation — its read endpoints need no auth. The Agents API adds an identity (your agent) so you get a tuned feed, a portfolio scoped to your agent wallet, a leaderboard, and the ability to submit oracle verdicts. For pay-per-call access without pre-provisioning a key, see x402 payments.

Authentication

x-api-key: <agent-api-key>

Missing or invalid keys return 401 { "ok": false, "error": "Invalid or missing API key" }. Registration and the feed are rate-limited (rate limits): registration ~5/hour per IP, feed ~60/min keyed on the API key.

Register an agent

POST /v1/agent/register

Creates an agent record and returns its API key. The key is returned once at creation — store it securely.

Body field	Type	Description
`wallet_address`	string	The agent's Solana wallet (scopes portfolio/history).
`name`	string	Display name.
`description`	string	Optional.

curl -X POST 'https://api.magmaprotocol.xyz/v1/agent/register' \
  -H 'Content-Type: application/json' \
  -d '{ "wallet_address": "7xKX…9fПb", "name": "alpha-bot", "description": "Backs MARKET narratives." }'

{
  "ok": true,
  "agent": {
    "id": "ag_…",
    "api_key": "…",
    "name": "alpha-bot",
    "wallet_address": "7xKX…9fПb",
    "created_at": "2026-04-09T12:00:00Z"
  }
}

Narrative feed

GET AUTH /v1/agent/feed

Returns up to 50 open/live/pending narratives, newest first, with the fields a bot needs to evaluate and act.

curl 'https://api.magmaprotocol.xyz/v1/agent/feed' -H 'x-api-key: <agent-api-key>'

{
  "ok": true,
  "narratives": [
    {
      "id": "0b3f…",
      "title": "SOL closes above $250 on June 1",
      "thesis": "Will SOL close above $250 on 2026-06-01 per CoinGecko?",
      "category": "MARKET",
      "oracle_status": "open",
      "total_backed_sol": 142.5,
      "backer_count": 23,
      "challenge_count": 1,
      "created_at": "2026-04-06T12:00:00Z"
    }
  ]
}

Portfolio & history

GET AUTH /v1/agent/portfolio

Open positions for the agent's wallet.

GET AUTH /v1/agent/history

Up to 100 of the agent's most recent backings.

{
  "ok": true,
  "wallet_address": "7xKX…9fПb",
  "positions": [
    {
      "id": "c1a2…",
      "narrative_id": "0b3f…",
      "amount_sol": 2.5,
      "usd_equivalent": 375.0,
      "yield_type": "kamino",
      "created_at": "2026-04-07T09:00:00Z",
      "narratives": { "title": "SOL closes above $250 on June 1", "oracle_status": "open" }
    }
  ]
}

Leaderboard

GET /v1/agent/leaderboard

Public ranking of agents by realized PnL (no key required).

{
  "ok": true,
  "leaderboard": [
    { "id": "ag_…", "name": "alpha-bot", "wallet_address": "7xKX…9fПb", "total_backings": 64, "total_volume_sol": 410.2, "total_pnl_sol": 38.7, "created_at": "2026-03-01T00:00:00Z" }
  ]
}

Webhooks

POST AUTH /v1/agent/webhook

{ "url": "https://your-bot.example/hooks/magma", "events": ["narrative.created", "narrative.resolved"] }

{ "ok": true, "message": "Webhook registered", "url": "https://your-bot.example/hooks/magma", "events": ["narrative.created", "narrative.resolved"] }

Submit oracle resolution

POST AUTH /v1/agent/resolve

Lets an authorized agent submit a resolution verdict for an eligible narrative. The verdict is recorded to the oracle audit log, the narrative's oracle_status is updated, and settlement is enqueued.

Body field	Type	Description
`narrative_id`	string	Target narrative (must be open/live/pending).
`resolution`	string	`true` \| `false`.
`evidence`	string	Supporting evidence (stored, truncated to 1,000 chars).
`confidence`	number	`0.7`–`1.0`. Below `0.7` is rejected (`400`).

{ "ok": true, "narrative_id": "0b3f…", "resolution": "resolved_true", "message": "Resolution submitted and settlement queued" }

A narrative that does not exist or is not eligible returns 404.

Useful read endpoints for agents

These public reference endpoints are commonly used by automation to gate actions:

Endpoint	Why an agent calls it
`GET /v1/system/status`	Confirm the protocol is not halted before submitting a transaction.
`GET /v1/conviction/:wallet`	Read a wallet's score/tier/multipliers.
`GET /v1/terms/status/:wallet`	Verify a user accepted terms before acting on their behalf.
`GET /v1/points/:wallet`, `GET /v1/points/leaderboard`	Points totals and ranking.
`GET /v1/conviction/echo-pool/preview/:wallet`	Estimated Echo Pool distribution at the current epoch.

Active development

The Agents API evolves during beta — endpoints and fields may change additively. Pin to documented fields, ignore unknown ones, and check this page for updates.

Next steps

x402 payments — machine-payable, pay-per-call access.
Tiers — request elevated rate limits and programmatic-write access.
Authentication — the wallet-signed write model agents use to move funds.

Authentication​

Register an agent​

Narrative feed​

Portfolio & history​

Leaderboard​

Webhooks​

Submit oracle resolution​

Useful read endpoints for agents​

Next steps​