# x402 Stacks API

> Pay-per-use API powered by x402 v2 protocol on Stacks blockchain.
> Agents pay per request via STX, sBTC, or USDCx — no API keys needed.

**Production:** https://x402.aibtc.com
**Staging:** https://x402.aibtc.dev
**OpenAPI Spec:** https://x402.aibtc.com/openapi.json
**Agent Card:** https://x402.aibtc.com/.well-known/agent.json

For the full aibtc agent platform (registration, messaging, identity), see https://aibtc.com/llms.txt

## What Is x402?

x402 is an HTTP payment protocol that enables pay-per-use APIs. When a request
lacks payment, the server returns HTTP 402 with payment requirements. The client
signs a Stacks transaction and retries with the payment signature.

This API supports x402 v2 (Coinbase-compatible) with Stacks blockchain payments.

Canonical public payment lifecycle:
- `requires_payment -> queued -> broadcasting -> mempool -> confirmed | failed | replaced | not_found`
- `submitted` is never caller-facing
- relay-owned `paymentId` is the stable in-flight identity
- this service keeps immediate pay-per-call behavior during rollout, but any surfaced payment status follows the canonical lifecycle and may include `checkStatusUrl`

## Pricing Tiers

| Tier     | Cost          | Endpoints                                    |
|----------|---------------|----------------------------------------------|
| free     | 0             | GET /inference/*/models, /, /health, /topics |
| standard | 0.001 STX     | All paid endpoints (hashing, stacks, storage)|
| dynamic  | varies        | OpenRouter LLM (cost + 20% margin)           |

**Token types:** STX, sBTC, USDCx (Circle USDC via xReserve)
Use `X-PAYMENT-TOKEN-TYPE` header to select token (default: STX).

Approximate standard pricing:
- 0.001 STX ≈ $0.0005 USD at $0.50/STX
- 0.001 STX ≈ 0.05 satoshis sBTC equivalent
- 0.001 STX ≈ 0.001 USDCx equivalent

## How to Make a Paid Request (x402 v2 Flow)

**Step 1 — Send request without payment:**
```
POST https://x402.aibtc.com/hashing/sha256
Content-Type: application/json

{"data": "hello world"}
```

**Step 2 — Receive 402 Payment Required:**
```
HTTP/1.1 402 Payment Required
payment-required: <base64-encoded PaymentRequiredV2>
```

Decode the `payment-required` header (base64 JSON) to get:
- `payTo`: Stacks address to pay
- `amount`: token amount (in microSTX, sats, or microUSDCx)
- `asset`: token contract address (for sBTC/USDCx)
- `network`: stacks:1 (mainnet) or stacks:2147483648 (testnet)

**Step 3 — Sign and retry:**
```
POST https://x402.aibtc.com/hashing/sha256
Content-Type: application/json
payment-signature: <base64-encoded PaymentPayloadV2>

{"data": "hello world"}
```

**Step 4 — Success:**
```
HTTP/1.1 200 OK
payment-response: <base64-encoded PaymentResponseV2>

{"ok": true, "hash": "b94d27b9934d3e08...", "algorithm": "SHA-256", ...}
```

The easiest way to handle this flow: use the AIBTC MCP server's `execute_x402_endpoint` tool
— it handles payment signing automatically.

## API Categories

| Category    | Endpoints                                          | Pricing  |
|-------------|---------------------------------------------------|----------|
| inference   | /inference/openrouter/* (100+ models)              | dynamic  |
| inference   | /inference/cloudflare/* (Cloudflare AI models)     | standard |
| stacks      | /stacks/* (address, decode, profile, verify)       | standard |
| hashing     | /hashing/* (sha256, sha512, keccak256, hash160...) | standard |
| storage     | /storage/kv, paste, db, sync, queue, memory        | standard |

**Safety:** Storage write operations (KV set, paste create, memory store) are
background-scanned for safety using Cloudflare AI (Llama 3.1 8B). Scanning is
flag-first and non-blocking — writes succeed regardless of scan result.

## Quick Examples

**SHA-256 hash (most common starting point):**
```bash
# Without payment (get 402):
curl -X POST https://x402.aibtc.com/hashing/sha256 \
  -H "Content-Type: application/json" \
  -d '{"data": "hello world"}'

# With payment:
curl -X POST https://x402.aibtc.com/hashing/sha256 \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64-PaymentPayloadV2>" \
  -d '{"data": "hello world"}'
```

**List OpenRouter models (free):**
```bash
curl https://x402.aibtc.com/inference/openrouter/models
```

**Check x402 payment manifest:**
```bash
curl https://x402.aibtc.com/x402.json
```

## Documentation

- Quick-start (this file): https://x402.aibtc.com/llms.txt
- Full reference: https://x402.aibtc.com/llms-full.txt
- Topic docs index: https://x402.aibtc.com/topics
- OpenAPI spec: https://x402.aibtc.com/openapi.json
- x402 payment manifest: https://x402.aibtc.com/x402.json
- Interactive docs: https://x402.aibtc.com/docs (Swagger UI)

Topic deep-dives:
- Inference: https://x402.aibtc.com/topics/inference
- Hashing: https://x402.aibtc.com/topics/hashing
- Storage: https://x402.aibtc.com/topics/storage
- Payment flow: https://x402.aibtc.com/topics/payment-flow