Call your first API in five minutes

1. Send an unpaid request

Every product starts without credentials. POST to the endpoint and the server answers 402 Payment Required with the x402 challenge: the price, the USDC contract, the receiving wallet, and the resource being priced.

curl -X POST https://apisphere.us.ci/api/v1/crypto-price \
  -H "Content-Type: application/json" \
  -d '{"symbols": ["btc", "eth"]}'

{
  "x402Version": 2,
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "1000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0xRECEIVING_WALLET",
      "resource": "https://apisphere.us.ci/api/v1/crypto-price",
      "description": "Real-time crypto price",
      "mimeType": "application/json",
      "maxTimeoutSeconds": 60
    }
  ]
}

2. Pay, then retry with the payment header

Sign the payment with any wallet that holds USDC on Base (amounts are atomic USDC units with 6 decimals, so $0.001 is "1000"), then repeat the same request with the signed payload in the X-PAYMENT header. The server verifies it with the configured x402 facilitator before running your handler.

An invalid or missing payment returns 402 again. A GET on a paid endpoint only advertises the challenge - data is served over POST.

curl -X POST https://apisphere.us.ci/api/v1/crypto-price \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <signed-payment-payload>" \
  -d '{"symbols": ["btc", "eth"]}'

3. Keep context with sessions (optional)

Create a session once, then pass it back on every call. The server remembers your last 10 calls for one hour, so follow-ups stay in context without resending history.

curl -X POST https://apisphere.us.ci/api/sessions

curl -X POST https://apisphere.us.ci/api/v1/geocode \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <signed-payment-payload>" \
  -H "X-Session-Id: sess_7f3a9c2e-1b4d-4f6a-8c2e-9d1f5a3b7c4e" \
  -d '{"query": "Monas, Jakarta"}'

4. Limits and errors

Calls are rate limited per client (120 requests per minute by default). Exceeding it returns 429 with a Retry-After header - back off and retry; the limit protects unpaid probing, it never consumes payment.

• 400 - invalid request body (see each endpoint page for its schema).
• 402 - missing or invalid payment; read the challenge and retry.
• 405 - GET with a payment on a paid endpoint; use POST with X-PAYMENT.
• 429 - rate limited; honor Retry-After and retry.
• 500 - internal error; every response carries X-Request-Id for support.
• 502 - upstream provider error; safe to retry the same request.

5. Use the MCP server instead

MCP-capable clients (Claude, Cursor, Codex) can call both products as tools. With PRIVATE_KEY set the server pays the x402 challenge for you; without it, it returns the challenge so you can pay out of band.

PRIVATE_KEY=0x... node scripts/mcp-server.mjs

{
  "mcpServers": {
    "apisphere": {
      "command": "node",
      "args": ["scripts/mcp-server.mjs"],
      "env": { "PRIVATE_KEY": "0x..." }
    }
  }
}