REST API reference

Two plain-HTTP endpoints live alongside the MCP server, on the same host:

https://mcp.axiomstack.dev

POST /v1/topup is the x402 USDC quota top-up; GET /health is liveness. (Attestation requests go through the MCP tools, not REST.)

POST /v1/topup

Buy attestation quota by paying USDC. Uses the x402 payment protocol with the Coinbase Developer Platform (CDP) facilitator for settlement. Two-step flow:

Step 1 — request requirements (no payment). Send your bearer key and the amount; the server replies 402 with the payment requirements.

POST /v1/topup HTTP/1.1
Host: mcp.axiomstack.dev
Authorization: Bearer axm_live_<your key>
Content-Type: application/json

{ "amount_usdc_micros": 25000000 }

You may instead send { "amount_usdc": 25 } (dollars), or {} to default to your tier's pack price.

// 402 Payment Required
{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana-devnet",
      "asset": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
      "maxAmountRequired": "25000000",
      "payTo": "6pPcyDr16FJkZrh2s4ANfcSdUcBZKgD2KquXLUfuA3B3",
      "resource": "https://mcp.axiomstack.dev/v1/topup",
      "maxTimeoutSeconds": 120,
      "extra": { "decimals": 6, "symbol": "USDC", "feePayer": "GVJJ7rdGiXr5xaYbRwRbjfaJL7fmwRygFi1H6aGqDveb" }
    }
  ],
  "error": "X-PAYMENT header is required"
}

payTo is the treasury owner wallet — the facilitator derives the destination token account (ATA) via ATA(payTo, asset). extra.feePayer is the facilitator's fee payer: build it as your transaction's fee payer so the facilitator signs + pays gas at settle.

The step-1 request with cURL (returns the 402 requirements; no payment, no charge):

curl -i -X POST https://mcp.axiomstack.dev/v1/topup \
  -H "Authorization: Bearer axm_live_<your key>" \
  -H "Content-Type: application/json" \
  -d '{"amount_usdc_micros": 25000000}'

Step 2 — pay. Build a signed x402 exact Solana payment (a v0 transaction transferring maxAmountRequired USDC to the derived ATA, fee payer = the facilitator), base64-encode the payment payload into the X-PAYMENT header, and retry. See the USDC top-up guide for the exact transaction recipe.

POST /v1/topup
Authorization: Bearer axm_live_<your key>
X-PAYMENT: <base64 payment payload>
Content-Type: application/json

{ "amount_usdc_micros": 25000000 }

// 200 OK   (+ X-PAYMENT-RESPONSE header)
{
  "credited_attestations": 100,
  "usdc_quota_remaining": 100,
  "topup_tx_sig": "4ZePiey9…PWjW",
  "tier": "developer"
}

Settlement steps the server performs: CDP /verify → CDP /settle (broadcasts on-chain) → independent on-chain re-verification that the USDC landed in the treasury ATA → idempotent quota credit.

Idempotency: crediting is keyed on the settled tx_sig; replaying the same settled payment never double-credits (returns 409 already_credited).

Status codes:

See Pricing & tiers for how an amount maps to credited attestations (marginal-rate math).

GET /health

Liveness probe. No auth.

curl https://mcp.axiomstack.dev/health
# {"status":"ok","service":"axiom-oracle-mcp"}