Access Tiers

API access is organized into tiers that set your rate limits and which capabilities are unlocked. Tiers are attached to an API key; pass the key on your requests to be evaluated at your tier rather than the anonymous IP limit.

Beta status

Paid tier upgrades and billing are not yet active. During beta every issued key sits on the Free tier. Paid tiers (and pricing) activate post-TGE. The table below describes the planned structure.

Tier comparison

Capability	Free	Pro	Enterprise
Requests per minute	60	300	1,000
Narrative feed access	✅	✅	✅
Conviction score reads	✅	✅	✅
System status	✅	✅	✅
Points leaderboard	✅	✅	✅
Programmatic backing	❌	✅	✅
Programmatic submission	❌	✅	✅
Webhook subscriptions	❌	✅	✅
WebSocket feed	❌	❌	✅
Dedicated support	❌	❌	✅
Price	Free	TBD post-TGE	TBD post-TGE

The Free tier covers all read access. Programmatic writes (backing, submission) and webhooks are Pro and above. See Rate limits for how quotas are signalled and the per-endpoint sub-limits that apply on top of your tier.

Using your API key

Pass the key in the x-api-key header on every request:

curl 'https://api.magmaprotocol.xyz/v1/narratives' \
  -H 'x-api-key: mgma_abcd1234_<64-hex-secret>'

Keys have the format:

mgma_<4hex>_<64hex>

Shown once

Your key's secret is shown only once at creation. Store it securely (a secrets manager or env var) and never embed it in a client bundle. If a key leaks, revoke it (below) and issue a new one.

When you exceed your tier's limit you receive 429:

{ "error": "Rate limit exceeded", "tier": "free", "limit": 60, "retry_after": "60s" }

Key management

Action	Endpoint	Notes
List your keys	GET /v1/apikeys/{wallet_address}	Keys issued to a wallet.
Revoke a key	POST /v1/apikeys/revoke	Body: { "id": "<key-uuid>", "wallet_address": "<wallet>" }.

curl -X POST 'https://api.magmaprotocol.xyz/v1/apikeys/revoke' \
  -H 'Content-Type: application/json' \
  -d '{ "id": "key-uuid", "wallet_address": "7xKX…9fПb" }'

Requesting elevated access

API keys are issued manually during beta. To request a key or a higher tier:

1. Reach out to the MAGMA team via Discord or email.
2. Tell us your wallet address, intended use case, and expected request volume.
3. We provision a key (Free tier during beta) scoped to your wallet.

Post-TGE, tier upgrades will be self-serve via the MAGMA dashboard, with pricing announced closer to TGE.

Building an agent?

If you're automating MAGMA — bots, trading agents, resolution workers — start with the AI Agents API, which has its own registration flow and feed limits, and consider x402 payments for machine-payable, pay-per-call access without pre-provisioning a key.