{"name":"x402 Stacks Sponsor Relay","description":"Gasless transaction relay and x402 V2 spec-compliant facilitator for AI agents on the Stacks blockchain. Accepts pre-signed sponsored transactions, covers the network fee, verifies payment parameters locally, and broadcasts directly to the Stacks network. Implements x402 V2 facilitator API (POST /settle, POST /verify, GET /supported) for use with standard x402 client libraries. Supports STX, sBTC, and USDCx tokens. API keys provisioned for free via BTC or STX signature.","url":"https://x402-relay.aibtc.com","provider":{"organization":"AIBTC Working Group","url":"https://aibtc.com"},"version":"1.33.2","documentationUrl":"https://x402-relay.aibtc.com/llms.txt","openApiUrl":"https://x402-relay.aibtc.com/openapi.json","documentation":{"quickStart":"https://x402-relay.aibtc.com/llms.txt","fullReference":"https://x402-relay.aibtc.com/llms-full.txt","openApiSpec":"https://x402-relay.aibtc.com/openapi.json","topicDocs":{"index":"https://x402-relay.aibtc.com/topics","sponsoredTransactions":"https://x402-relay.aibtc.com/topics/sponsored-transactions","apiKeys":"https://x402-relay.aibtc.com/topics/api-keys","authentication":"https://x402-relay.aibtc.com/topics/authentication","errors":"https://x402-relay.aibtc.com/topics/errors","x402V2Facilitator":"https://x402-relay.aibtc.com/topics/x402-v2-facilitator","queueManagement":"https://x402-relay.aibtc.com/topics/queue-management","agentPayments":"https://x402-relay.aibtc.com/topics/agent-payments"},"relatedPlatform":"https://aibtc.com/llms.txt"},"capabilities":{"streaming":false,"pushNotifications":false,"stateTransitionHistory":false,"x402Facilitator":true,"x402FacilitatorSpec":"x402-v2","x402FacilitatorSpecUrl":"https://github.com/coinbase/x402/blob/main/specs/x402-specification-v2.md","queueVisibility":true,"queueCancellation":true},"authentication":{"schemes":["bearer"],"description":"Bearer token (API key) required for POST /sponsor. Provision a free key via POST /keys/provision (BTC sig) or POST /keys/provision-stx (STX sig). Optional SIP-018 structured data auth available on POST /relay and POST /sponsor. SIP-018 auth required for GET /queue/:senderAddress and DELETE /queue/:senderAddress/:walletIndex/:sponsorNonce."},"defaultInputModes":["application/json"],"defaultOutputModes":["application/json"],"network":{"production":{"url":"https://x402-relay.aibtc.com","chain":"mainnet","chainId":1},"staging":{"url":"https://x402-relay.aibtc.dev","chain":"testnet","chainId":2147483648}},"supportedTokens":["STX","sBTC","USDCx"],"relatedServices":{"aibtcPlatform":"https://aibtc.com","github":"https://github.com/aibtcdev/x402-sponsor-relay","x402Spec":"https://github.com/coinbase/x402/blob/main/specs/x402-specification-v2.md"},"skills":[{"id":"relay-transaction","name":"Relay Sponsored Transaction","description":"Submit a pre-signed Stacks sponsored transaction for native settlement. The relay verifies payment params locally, pays the network fee, and broadcasts directly. Accepts STX, sBTC, and USDCx token transfers. No API key required. POST /relay with { transaction, settle: { expectedRecipient, minAmount, tokenType } }. Returns { txid, settlement, sponsoredTx, receiptId }. settlement.status is 'confirmed' (immediate) or 'pending' (60s timeout — safe to poll /verify/:receiptId). Idempotent: same tx hex returns cached result within 5 minutes.","tags":["gasless","sponsored","stacks","x402","settlement"],"examples":["Relay a sponsored STX transfer without paying fees","Submit a gasless sBTC transaction via x402","Settle an x402 payment with the sponsor relay"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"sponsor-transaction","name":"Sponsor and Broadcast Transaction","description":"Sponsor a pre-signed Stacks transaction and broadcast it directly to the network. No facilitator settlement — useful for non-payment transactions. Requires API key (Bearer token). POST /sponsor with { transaction }. Returns { txid, fee }. Optional SIP-018 auth via auth field.","tags":["gasless","sponsored","broadcast","stacks"],"examples":["Broadcast a sponsored transaction directly","Sponsor a contract call without holding STX","Broadcast a gasless ERC-8004 identity registration"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"provision-api-key","name":"Provision API Key","description":"Get a free-tier API key for POST /sponsor by signing a known message with your Bitcoin key. Supports all address types: P2PKH (1...) and P2SH (3...) use BIP-137; native SegWit (bc1q...) and Taproot (bc1p...) use BIP-322. POST /keys/provision with { btcAddress, signature, message }. Self-service path: message = 'Bitcoin will be the currency of AIs | <ISO-timestamp>'. Also available via Stacks signature: POST /keys/provision-stx. Returns apiKey (store securely — shown once).","tags":["api-key","provisioning","bitcoin","stacks","authentication"],"examples":["Get an API key using my Bitcoin signature","Provision a relay key for sponsored transactions","Get a free key by signing with my Stacks wallet"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"verify-receipt","name":"Verify Payment Receipt","description":"Verify a payment receipt created by a successful POST /relay call. GET /verify/:receiptId returns status, sender, settlement details, and accessCount. Receipts are valid for 30 days.","tags":["receipt","verification","payment"],"examples":["Check if a receipt is still valid","Verify a payment receipt from a relay transaction"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"access-resource","name":"Access Receipt-Gated Resource","description":"Use a payment receipt to access a gated resource or proxy a downstream request. POST /access with { receiptId, resource?, targetUrl? }. The resource field must match the resource in the original settle options. If targetUrl is provided (HTTPS only), the relay proxies the request.","tags":["access","receipt","proxy","x402"],"examples":["Access a protected endpoint using a relay receipt","Proxy a request to a downstream service using a payment receipt"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"fee-estimates","name":"Get Fee Estimates","description":"Get clamped fee estimates for Stacks transactions. GET /fees returns estimates for token_transfer, contract_call, and smart_contract at low/medium/high priority. No authentication required. Values in microSTX.","tags":["fees","estimation","stacks"],"examples":["What are the current STX transaction fees?","Get fee estimates before building a transaction"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"health-check","name":"Service Health Check","description":"Check relay health and cached sponsor readiness. GET /health is the thin service summary, while GET /status/sponsor is the canonical cached sponsor status surface. Use before sending transactions to verify the relay is operational.","tags":["health","monitoring","status"],"examples":["Is the relay healthy?","Check relay status before submitting a transaction"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"queue-management","name":"Agent Queue Visibility and Cancellation","description":"Inspect your own pending sponsored transaction queue and cancel entries without operator intervention. GET /queue/:senderAddress returns queued, dispatched, replaying, and replay_buffer entries across all sponsor wallets. DELETE /queue/:senderAddress/:walletIndex/:sponsorNonce cancels a specific entry: queued→deleted, dispatched→replaying (flushed in next alarm cycle), replaying→deleted, replay_buffer→deleted. Both endpoints require SIP-018 auth (action: 'queue-read' / 'queue-cancel') — recovered signer must match :senderAddress. See /topics/queue-management for details.","tags":["queue","cancel","nonce","sip018","auth"],"examples":["Show me my pending sponsored transactions","Cancel a stuck queued transaction","Check if my transaction is still in the relay queue"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"x402-v2-facilitator","name":"x402 V2 Facilitator","description":"Spec-compliant x402 V2 facilitator (coinbase/x402 spec section 7). POST /settle — verifies payment params locally and broadcasts the transaction; auto-sponsors transactions with empty sponsor slots (fee=0 / all-zeros signer); returns { success, transaction, network, payer }. POST /verify — local validation only, no broadcast; returns { isValid, invalidReason?, payer? }. GET /supported — returns supported payment kinds (x402Version: 2, scheme: 'exact', CAIP-2 network). CAIP-2 networks: 'stacks:1' (mainnet), 'stacks:2147483648' (testnet). Assets: 'STX', 'sBTC', or CAIP-19 contract address. Returns HTTP 200 for successful settle/verify, HTTP 400 for malformed schema, and HTTP 409 Conflict when a payment-identifier collision is detected. Idempotent: same tx hex returns cached result within 5 minutes. Supports 'payment-identifier' extension: include a stable pay_<uuid> in paymentPayload.extensions for idempotency across tx rebuilds. See /topics/x402-v2-facilitator for payment-identifier details.","tags":["x402","facilitator","settlement","stacks","caip2"],"examples":["Settle an x402 V2 payment on Stacks","Verify an x402 payment before broadcasting","Check supported payment kinds for this facilitator","Use this relay as an x402 V2 facilitator in my client"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"agent-payment-guide","name":"Agent Payment Guide","description":"Payment guide for agents making x402 payments across aibtc services. Covers mental model (you sign, relay pays fee), per-service flows (inbox, news, MCP tools, skills), settlement status interpretation (confirmed/pending/failed), common errors, and network constants. GET /topics/agent-payments for condensed plaintext. Full guide: https://github.com/aibtcdev/x402-sponsor-relay/blob/main/docs/agent-payment-guide.md","tags":["x402","payment","guide","errors","settlement","stacks"],"examples":["How do I make an x402 payment on Stacks?","What does CLIENT_BAD_NONCE mean and how do I fix it?","What is the difference between pending and confirmed settlement?","Which endpoint do I use to pay for aibtc.com inbox messages?"],"inputModes":["application/json"],"outputModes":["text/plain"]}]}