x402 paid API

StonkTrader supports x402 for agents and applications that prefer per-request payments instead of API keys or subscriptions.

Paid capabilities

Every capability costs 0.001 USDG per successful request.

Stock Token market snapshot

GET https://api.stonktrader.finance/x402/stock-token-snapshot?symbols=AAPL,NVDA

The response combines normalized Stock Token quotes with StonkTrader-calculated midpoint, spread, spread basis points, market status, and chain deployment details.

eToro market data

The paid eToro resources mirror the normalized response contracts of the free /etoro/* routes:

GET https://api.stonktrader.finance/x402/etoro/instruments?q=AAPL&limit=10
GET https://api.stonktrader.finance/x402/etoro/quote?symbol=AAPL
GET https://api.stonktrader.finance/x402/etoro/exchanges
GET https://api.stonktrader.finance/x402/etoro/candles?symbol=AAPL&interval=OneDay&count=30&direction=desc

The StonkTrader backend authenticates with eToro. x402 callers do not provide eToro public or private keys; they only satisfy the payment challenge. Results use the same Redis-backed cache as the corresponding public routes.

Discover the payment requirement

Call the resource without a payment signature:

curl -i "https://api.stonktrader.finance/x402/stock-token-snapshot?symbols=AAPL"

For example, discover the requirement for a paid eToro quote with:

curl -i "https://api.stonktrader.finance/x402/etoro/quote?symbol=AAPL"

The API responds with 402 Payment Required and a PAYMENT-REQUIRED header. Decode and sign that exact challenge with an x402-compatible wallet client, then retry the same URL with the resulting PAYMENT-SIGNATURE header.

Do not reconstruct the payment amount, asset, network, or receiver from this page. The live challenge is authoritative.

Successful response

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "tokenSymbol": "AAPL",
        "currency": "USD",
        "bid": "213.45",
        "ask": "213.47",
        "midpoint": "213.46",
        "spread": "0.02",
        "spreadBps": "0.936944",
        "dailyTradingVolume": "48293710",
        "marketStatus": "trading",
        "generatedAt": "2026-09-02T05:00:00Z",
        "deployments": [
          {
            "chainId": 4663,
            "contractAddress": "0xAbCdEf0123456789AbCdEf0123456789AbCdEf01"
          }
        ]
      }
    ]
  }
}

A settled request exposes its payment result in the PAYMENT-RESPONSE header.

Machine-readable contract

The Marketplace-ready OpenAPI contract is available at:

https://api.stonktrader.finance/openapi.json

Every paid operation includes Naven access metadata, x402 payment discovery fields, complete input and output schemas, and a stable operationId.