x402 (HTTP 402 micropayments)

🌟 New (June 2026): Stellar settlement is live. Sly’s governed x402 flow now settles on stellar:testnet under the same L1–L5 governance loop as Base — fees sponsored, ~5s finality, agentic identity baked into the signed witness receipt. See Settling on Stellar for the full guide.

x402 is a protocol from Coinbase that repurposes the long-reserved HTTP 402 Payment Required status code for micropayment flows. The pattern:

Client calls a protected endpoint
Server responds 402 Payment Required with a payment quote
Client pays (typically stablecoin, on-chain)
Client retries with a payment proof
Server verifies and returns the real response

This enables pay-per-request API monetization with no sign-up, no API keys, no subscriptions. Ideal for machine-to-machine commerce where agents discover and pay for APIs at runtime.

The request/response dance

First call — no payment:

GET /api/expensive-inference HTTP/1.1
Host: inference.example.com

Server response:

HTTP/1.1 402 Payment Required
Content-Type: application/json
X-Payment-Required: true

{
  "price": "0.05",
  "currency": "USDC",
  "network": "base",
  "receiver": "0xreceiver...",
  "payment_request_id": "x402_pr_...",
  "expires_in": 60
}

Client pays via Sly:

curl -X POST https://api.getsly.ai/v1/x402/pay \
  -H "Authorization: Bearer agent_..." \
  -d '{
    "payment_request_id": "x402_pr_...",
    "from_wallet_id": "wal_..."
  }'

Response:

{
  "id": "x402_pay_...",
  "proof": "0xproof...",
  "tx_hash": "0xsettlement...",
  "amount": "0.05",
  "currency": "USDC"
}

Client retries with proof:

GET /api/expensive-inference HTTP/1.1
Host: inference.example.com
X-Payment-Proof: 0xproof...

Server verifies and responds:

HTTP/1.1 200 OK
Content-Type: application/json

{ "inference_result": { ... } }

The SDK shortcut

The SDK wraps all of this into one call:

import { Sly } from '@sly_ai/sdk';
const sly = new Sly({ apiKey: process.env.SLY_API_KEY });

// Automatic 402 handling — retries with proof once paid
const result = await sly.x402.fetch('https://inference.example.com/api/expensive-inference', {
  walletId: 'wal_...',
});

Under the hood: catch 402, parse quote, call /v1/x402/pay, retry with X-Payment-Proof.

Serving x402 endpoints (API provider side)

curl -X POST https://api.getsly.ai/v1/x402/endpoints \
  -d '{
    "url": "https://inference.example.com/api/expensive-inference",
    "price": "0.05",
    "currency": "USDC",
    "network": "base",
    "receiver_wallet_id": "wal_...",
    "rate_card": [
      { "path": "/api/expensive-inference", "price": "0.05" },
      { "path": "/api/cheap-lookup", "price": "0.001" }
    ]
  }'

When a client pays, Sly settles on-chain to receiver_wallet_id and issues the payment_proof that the API will verify.

Verifying proofs (API provider side)

When your server receives a request with X-Payment-Proof:

curl -X POST https://api.getsly.ai/v1/x402/verify \
  -d '{
    "proof": "0xproof...",
    "expected_price": "0.05",
    "expected_currency": "USDC"
  }'

Returns { "valid": true, "payment_id": "..." } or a failure reason. The SDK and Sly server-side middleware handle this for you.

x402 facilitator (sandbox only)

Sandbox endpoints have a test facilitator that issues mock proofs without real on-chain settlement:

curl -X POST https://sandbox.getsly.ai/v1/x402/facilitator/pay \
  -d '{ "amount": "0.05", "currency": "USDC" }'

Production traffic uses the open Coinbase-operated facilitator at https://www.x402.org/facilitator, which supports both Base mainnet (eip155:8453) and Stellar mainnet (stellar:pubnet — Phase B). For rail-specific guides, see Settling on Base, Settling on Stellar, or the side-by-side comparison and selectRail() decision function.

x402 bridge

Sly includes an x402 → Circle bridge for tenants that want to accept x402 payments but settle in fiat. Bridges are configured per-endpoint.

Endpoints

Endpoint	Purpose
`POST /v1/x402/pay`	Execute payment for an x402 quote
`POST /v1/x402/verify`	Verify a payment proof
`POST /v1/x402/endpoints`	Register an x402-priced API endpoint
`GET /v1/x402/endpoints`	List registered endpoints
`GET /v1/x402/analytics/*`	Payment and usage metrics
`POST /v1/x402/facilitator/*`	Sandbox facilitator (testing only)
`POST /v1/x402/bridge/*`	On-chain → fiat bridging

When to use x402

You run an API and want per-call monetization (not subscriptions)
Consumers are agents that discover and pay for APIs at runtime — no sign-up flow
Price points are too low for traditional billing (fractions of a cent per call)
You want crypto-native settlement with no card networks in the loop

For traditional subscriptions, use UCP or AP2.

Get Started

Onboarding

Migration

Authentication

Core Concepts

Guides

Recipes

Architecture

Settlement & Treasury

Stellar

Protocols

Agent Platform

SDKs & Tools

Webhooks

Resources

x402 (HTTP 402 micropayments)

The request/response dance

The SDK shortcut

Serving x402 endpoints (API provider side)

Verifying proofs (API provider side)

x402 facilitator (sandbox only)

x402 bridge

Endpoints

When to use x402

​The request/response dance

​The SDK shortcut

​Serving x402 endpoints (API provider side)

​Verifying proofs (API provider side)

​x402 facilitator (sandbox only)

​x402 bridge

​Endpoints

​When to use x402

The request/response dance

The SDK shortcut

Serving x402 endpoints (API provider side)

Verifying proofs (API provider side)

x402 facilitator (sandbox only)

x402 bridge

Endpoints

When to use x402