Skip to content
StockKitStockKit Docs

x402 API

Every StockKit endpoint is also available pay-per-call under /v1/x402/*, gated by x402: no API key, no subscription, no signup. Pay a few cents in stablecoin per call and get the response back in the same request. This is the tier that lets agents, wallets, and marketplaces on Robinhood Chain and Base buy StockKit data directly, without a contract or an account.

The machine-readable contract for the whole API, including prices and input and output schemas for every paid route, is published at api.stockkit.dev/openapi.json. That is what agent registries such as x402scan crawl.

Endpoints

Section titled “Endpoints”
Endpoint Price
GET /v1/x402/research/:symbol $0.01
GET /v1/x402/quote $0.01
GET /v1/x402/portfolio/:address $0.01
GET /v1/x402/history/:symbol $0.01
POST /v1/x402/trade/build $0.02

Same parameters and response shapes as the free endpoints documented on the Research, Execution, Portfolio, and Market pages. The /v1/x402/* path is purely a payment wrapper around the same handlers; the free /v1/* routes stay open during the beta.

Settlement rails

Section titled “Settlement rails”

One request can pay on either of two networks. The 402 challenge always advertises both:

Network Asset Facilitator
Robinhood Chain (eip155:4663) USDG facilitator.meshgateway.co
Base (eip155:8453) USDC facilitator.payai.network

StockKit never holds a relayer key or touches either chain directly. Each facilitator verifies the signed payment and broadcasts the transfer; StockKit only checks the settlement result before serving the response.

The payment flow

Section titled “The payment flow”

StockKit speaks x402 v2 over the standard HTTP transport. Call a paid endpoint with no payment and you get a 402 whose PAYMENT-REQUIRED header carries the base64-encoded challenge with both accepted payment options. The same object is repeated as the JSON body so humans can read it:

Terminal window
curl -i https://api.stockkit.dev/v1/x402/research/NVDA
{
  "x402Version": 2,
  "error": "Payment is required (StockKit research).",
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:4663",
      "amount": "10000",
      "asset": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
      "payTo": "0x0E74F4793a144b0eB9c15CDB959B1D8bcAA5c9Cf",
      "maxTimeoutSeconds": 300,
      "extra": { "assetTransferMethod": "permit2", "spender": "0x402085c248EeA27D92E8b30b2C58ed07f9E20001" }
    },
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "10000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x0E74F4793a144b0eB9c15CDB959B1D8bcAA5c9Cf",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ],
  "resource": {
    "url": "https://api.stockkit.dev/v1/x402/research/NVDA",
    "description": "Company fundamentals from SEC EDGAR ...",
    "mimeType": "application/json"
  }
}

Routes that take query parameters or a JSON body also include an extensions.bazaar block describing the expected input, the same schema the OpenAPI document publishes.

Sign a payment for one of the accepts entries with an x402-compatible wallet or client, then retry the same request with the signed payload in the PAYMENT-SIGNATURE header. A successful response carries the settlement receipt in PAYMENT-RESPONSE (transaction hash, network, payer) alongside the normal JSON body. An invalid or failed payment returns another 402 with the rejection reason from the facilitator instead of a generic error.

Older clients that still send the v1 header names are also accepted: a payment in X-PAYMENT is honoured, and the receipt is mirrored to X-PAYMENT-RESPONSE.

The payment middleware runs before any parameter or body validation, so an unauthenticated probe always reaches the 402 challenge. That is what discovery crawlers rely on when they verify the listing against the live endpoint.

Any x402 v2 client works, for example PayAI’s agent tooling for Base, or a meshgateway-integrated wallet for Robinhood Chain.

Why pay-per-call

Section titled “Why pay-per-call”

  • No account, no key. Any wallet that can sign a payment can call the API immediately.

  • Discoverable by agents. The /openapi.json document marks every paid route with x-payment-info and a documented 402 response, which is the contract registries such as x402scan use to list an API. You can audit the live origin yourself:

    Terminal window
    npx -y @agentcash/discovery@latest discover https://api.stockkit.dev

  • Same data as the free tier. Pay-per-call is for callers who want to pay in-protocol instead of using the open beta endpoints, not a separate, lesser dataset.