x402 pay-per-call

Pay /v1/index and /v1/streams reads per call with x402 — the HTTP 402 standard, settled on Stacks. No card, no signup, no gas.

Experimental

The rail is a beta; surfaces, prices, and headers may change. Plans are the stable way to pay.

How it works

1. Call without a key

GET /v1/index/events?event_type=ft_transfer

HTTP/1.1 402 Payment Required
{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "stacks:1",
    "asset": "SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token",
    "amount": "21",
    "payTo": "SP2X…8KQ",
    "maxTimeoutSeconds": 60,
    "extra": { "nonce": "…" }
  }]
}

One accepts[] offer per token you can pay in (sBTC, STX, USDCx). The quote also rides back base64-encoded in a PAYMENT-REQUIRED response header, so any x402 client reads it without parsing the body.

2. Wrap fetch, hold a wallet

import { withX402, readX402Receipt } from "@secondlayer/sdk";

const x402fetch = withX402(fetch, { account });

const res = await x402fetch(
  "https://api.secondlayer.tools/v1/index/events?event_type=ft_transfer",
);

It selects an offer, signs the sponsored transfer (you pay zero gas), and retries with a PAYMENT-SIGNATURE header. The response streams immediately; settlement confirms on-chain behind it.

3. Read the receipt

const receipt = readX402Receipt(res);
// {
//   success: true,
//   state: "optimistic" | "confirmed",
//   txid: "0x4f…",
//   payer: "SP1Q4…2MVE",
//   network: "stacks:1"
// }

Every paid response carries the same receipt in a PAYMENT-RESPONSE header. Floor $0.001 per call.

Free vs. paid

Decided per request, in this order:

Caller	Result
Valid `sk-sl_` key	Never a 402; usage bills against your plan
Rail off (no funded `X402_SPONSOR_KEY`)	Keyless Index free, Streams key-mandatory. Live state: `GET /.well-known/x402` (`enabled: true` \| `false`)
Keyless `/v1/index`, first 1,000 reads per IP per day	`200`
Keyless `/v1/index` past that, or any keyless `/v1/streams`	`402` quote

Discovery and sessions

Standard x402 v2 wire, so any x402 client works. Discover the rail at GET /.well-known/x402 and the x-x402 block in the OpenAPI spec.

Steady consumers can hold either:

A session: one Streams payment covers up to 500 polls in the next hour on a PAYMENT-SESSION voucher.
A prepaid tab: deposit once, calls debit it instantly.

Deploy a subgraph

A paid POST /v1/subgraphs deploys an indexer owned by the paying wallet — $2, 7-day expiry, $0.50 to renew via POST /v1/subgraphs/{name}/renew. Claiming the account clears the expiry.