x402 agent access
Discover and pay for machine-readable market data with the x402 protocol.
The x402 surface lets automated clients pay per request for market data without creating a user session or managing a subscription. The API implements x402 version 2 on BNB Chain.
Discover products
The catalog is public:
curl "$BULGE_API_URL/x402"The catalog reports:
- protocol and version
- network (
eip155:56) - payment asset (BNB Chain USDT, 18 decimals)
- per-request price
- available method and path combinations
Products
| Route | Data product |
|---|---|
GET /x402/tokens | All supported bStocks with live prices |
GET /x402/tokens/{symbol} | One bStock with live price |
GET /x402/markets | Perpetual market snapshots |
GET /x402/markets/{symbol} | One perpetual market snapshot |
GET /x402/markets/{symbol}/candles?range=1D | Historical candles |
GET /x402/analysis/{symbol}/basis | Spot/perpetual cross-venue basis |
Payment flow
- The client requests a protected product without payment.
- The API responds with HTTP
402and a structured payment challenge. - The client selects the accepted exact-payment option and authorizes USDT payment on BNB Chain.
- The client retries the same request with the encoded payment proof.
- The payment is verified and settled.
- The API returns the requested JSON and exposes the payment response header.
The challenge is available in the PAYMENT-REQUIRED header and as a JSON body for compatibility. Successful settlement metadata is returned in PAYMENT-RESPONSE; the API also mirrors it to X-PAYMENT-RESPONSE.
Cross-venue basis
/x402/analysis/{symbol}/basis combines the BNB Chain bStock price and the corresponding perpetual snapshot. It is useful for monitoring divergence between spot and derivative venues.
Basis is context, not a guaranteed arbitrage opportunity. Clients must account for:
- quote freshness
- swap price impact and gas
- perpetual spread and slippage
- funding
- deposit and withdrawal latency
- token and venue risk
Client guidance
- Cache the catalog briefly, but treat its price and accepted payment option as changeable.
- Respect the timeout provided in the payment challenge.
- Make paid retries idempotent at the client workflow level.
- Store settlement metadata alongside the retrieved product for reconciliation.
- Never log private keys or raw wallet secrets.
- Distinguish
402payment requirements from temporary service failures.