Documentation Index Fetch the complete documentation index at: https://developers.fd.xyz/llms.txt
Use this file to discover all available pages before exploring further.
An AI agent buys one pair of “Classic Crew Socks - Black / M” ($12.99) from an ACP merchant, paying in USDC on Base Sepolia. Each step shows what the agent sends, what the merchant does behind the scenes, and what Prism returns.
1. Discovery The agent checks if the merchant supports ACP.
Agent → Merchant GET https://merchant.example/.well-known/acp.json
Agent receives: { "protocol" : { "name" : "acp" , "version" : "2026-04-17" , "supported_versions" : [ "2026-04-17" ] }, "api_base_url" : "https://merchant.example/acp/api" , "transports" : [ "rest" ], "capabilities" : { "services" : [ "checkout" , "product_feed" , "orders" ], "extensions" : [], "supported_currencies" : [ "usd" ], "supported_locales" : [ "en-US" ] } }
The agent confirms ACP is supported, extracts api_base_url, and proceeds.
2. Product Feed The agent fetches the merchant’s product feed and finds the item.
Agent → Merchant GET https://merchant.example/acp/api/product_feed
Agent receives: { "products" : [ { "id" : "prod_socks_001" , "title" : "Classic Crew Socks" , "description" : "Comfortable cotton crew socks" , "variants" : [ { "id" : "var_socks_blk_m" , "title" : "Black / M" , "price" : { "amount" : 1299 , "currency" : "usd" }, "available" : true , "options" : { "color" : "Black" , "size" : "M" } } ] } ] }
The agent selects var_socks_blk_m and proceeds to checkout.
3. Create Checkout Session The agent sends the item. The merchant calls Prism to get x402 payment requirements and returns them in the session.
Agent → Merchant POST https://merchant.example/acp/api/checkout_sessions Authorization : Bearer <agent_token> API-Version : 2026-04-17 Idempotency-Key : cs_create_socks_1 Content-Type : application/json { "line_items" : [ { "product_id" : "prod_socks_001" , "variant_id" : "var_socks_blk_m" , "quantity" : 1 } ] }
Merchant → Prism (background)POST https://prism-gw.fd.xyz/api/v2/merchant/acp/payment-requirements X-API-Key : prism_live_... Content-Type : application/json { "amount" : "1299" , "currency" : "usd" , "resource" : { "url" : "https://merchant.example/acp/api/checkout_sessions/cs_001" , "description" : "Purchase from Example Store" } }
Agent receives: { "id" : "cs_001" , "status" : "collecting_information" , "currency" : "usd" , "capabilities" : { "payment" : { "handlers" : [ { "id" : "x402" , "name" : "xyz.fd.prism_payment" , "version" : "2026-01-15" , "spec" : "https://prism-gw.fd.xyz/acp/spec.md" , "requires_delegate_payment" : false , "requires_pci_compliance" : false , "psp" : "prism" , "config_schema" : "https://prism-gw.fd.xyz/acp/config_schema.json" , "instrument_schemas" : [ "https://prism-gw.fd.xyz/acp/instrument_schema.json" ], "config" : { "x402Version" : 2 , "resource" : { "url" : "https://merchant.example/acp/api/checkout_sessions/cs_001" , "description" : "Purchase from Example Store" }, "accepts" : [ { "scheme" : "exact" , "network" : "eip155:84532" , "amount" : "12990000" , "asset" : "0x036c...cf7e" , "payTo" : "0x40a0...C4fD" , "maxTimeoutSeconds" : 300 , "extra" : { "name" : "USDC" , "version" : "2" } } ] } } ] }, "interventions" : { "supported" : [], "required" : [], "enforcement" : "conditional" }, "extensions" : [] }, "line_items" : [ { "product_id" : "prod_socks_001" , "variant_id" : "var_socks_blk_m" , "title" : "Classic Crew Socks - Black / M" , "quantity" : 1 , "unit_price" : { "amount" : 1299 , "currency" : "usd" } } ], "totals" : { "subtotal" : 1299 , "tax" : 0 , "shipping" : 0 , "total" : 1299 }, "required_fields" : [ "buyer.name" , "buyer.email" , "shipping_address" ] }
The agent reads status: "collecting_information" and required_fields. Buyer info and a shipping address are needed.
4. Session Update The agent provides buyer info and the shipping address. The merchant recalculates totals and re-fetches the Prism config with updated amounts.
Agent → Merchant PUT https://merchant.example/acp/api/checkout_sessions/cs_001 Authorization : Bearer <agent_token> API-Version : 2026-04-17 Idempotency-Key : cs_001_update_1 Content-Type : application/json { "buyer" : { "name" : "Alice Smith" , "email" : "alice@example.com" }, "shipping_address" : { "line1" : "123 Main St" , "city" : "San Francisco" , "state" : "CA" , "postal_code" : "94105" , "country" : "US" } }
Merchant → Prism (background, re-fetch with updated total)POST https://prism-gw.fd.xyz/api/v2/merchant/acp/payment-requirements X-API-Key : prism_live_... Content-Type : application/json { "amount" : "2002" , "currency" : "usd" , "resource" : { "url" : "https://merchant.example/acp/api/checkout_sessions/cs_001" , "description" : "Purchase from Example Store" } }
Agent receives: { "id" : "cs_001" , "status" : "ready_for_payment" , "currency" : "usd" , "capabilities" : { "payment" : { "handlers" : [ { "id" : "x402" , "name" : "xyz.fd.prism_payment" , "version" : "2026-01-15" , "config" : { "x402Version" : 2 , "resource" : { "url" : "https://merchant.example/acp/api/checkout_sessions/cs_001" , "description" : "Purchase from Example Store" }, "accepts" : [ { "scheme" : "exact" , "network" : "eip155:84532" , "amount" : "20020000" , "asset" : "0x036c...cf7e" , "payTo" : "0x40a0...C4fD" , "maxTimeoutSeconds" : 300 , "extra" : { "name" : "USDC" , "version" : "2" } } ] } } ] } }, "line_items" : [ { "product_id" : "prod_socks_001" , "variant_id" : "var_socks_blk_m" , "title" : "Classic Crew Socks - Black / M" , "quantity" : 1 , "unit_price" : { "amount" : 1299 , "currency" : "usd" } } ], "totals" : { "subtotal" : 1299 , "tax" : 104 , "shipping" : 599 , "total" : 2002 } }
Status is now ready_for_payment. Total: $20.02. The config.accepts amount has been updated to "20020000" (20.02 USDC).
5. Payment Authorization The agent extracts config from the handler and passes it to the wallet. No HTTP request goes out; everything happens locally in the wallet.
Wallet receives: config — x402 paymentRequirements with accepts[] Wallet selects: eip155:84532 (Base Sepolia), USDC — sufficient balance Wallet signs: ERC-3009 transferWithAuthorization inside the secure enclave Wallet returns: complete signed x402 payment object
The wallet output contains:
paymentPayload.accepted: the option the wallet chose (USDC on Base Sepolia)paymentPayload.payload.signature: EIP-712 signature over the authorizationpaymentPayload.payload.authorization: EIP-3009 params (exact value, exact recipient, time-limited)paymentRequirements: echo of the chosen accepts[] item
The private key never leaves the enclave. Only the signed authorization exits.
6. Complete Checkout The agent submits the signed wallet output as the credential, adding type: "default" discriminators.
Agent → Merchant POST https://merchant.example/acp/api/checkout_sessions/cs_001/complete Authorization : Bearer <agent_token> API-Version : 2026-04-17 Idempotency-Key : cs_001_complete_1 Content-Type : application/json { "payment_data" : { "handler_id" : "x402" , "instrument" : { "type" : "default" , "credential" : { "type" : "default" , "x402Version" : 2 , "paymentPayload" : { "x402Version" : 2 , "resource" : { "url" : "https://merchant.example/acp/api/checkout_sessions/cs_001" , "description" : "Purchase from Example Store" , "mimeType" : null }, "accepted" : { "scheme" : "exact" , "network" : "eip155:84532" , "amount" : "20020000" , "payTo" : "0x40a0...C4fD" , "maxTimeoutSeconds" : 300 , "asset" : "0x036c...cf7e" , "extra" : { "name" : "USDC" , "version" : "2" } }, "payload" : { "signature" : "0xef55...a71c" , "authorization" : { "from" : "0xC565...0573" , "to" : "0x40a0...C4fD" , "value" : "20020000" , "validAfter" : "1776664729" , "validBefore" : "1776665029" , "nonce" : "0xf1c1...1b55" } }, "extensions" : null }, "paymentRequirements" : { "scheme" : "exact" , "network" : "eip155:84532" , "amount" : "20020000" , "payTo" : "0x40a0...C4fD" , "maxTimeoutSeconds" : 300 , "asset" : "0x036c...cf7e" , "extra" : { "name" : "USDC" , "version" : "2" } } } } } }
Merchant → Prism (background)The merchant extracts paymentPayload and paymentRequirements from the credential (stripping the ACP type fields) and forwards them to Prism:
POST https://prism-gw.fd.xyz/api/v2/payment/settle X-API-Key : prism_live_... Content-Type : application/json { "paymentPayload" : { "...signed authorization..." }, "paymentRequirements" : { "...chosen accepts[] item..." } }
Prism executes the ERC-3009 transferWithAuthorization on Base Sepolia, verifies the transfer, and returns:
{ "success" : true , "payer" : "0xC565...0573" , "transaction" : "0x7a3b...1a2b" , "network" : "eip155:84532" }
Agent receives: { "id" : "cs_001" , "status" : "completed" , "order" : { "id" : "ord_001" , "checkout_session_id" : "cs_001" , "order_number" : "#1001" , "permalink_url" : "https://merchant.example/orders/ord_001" , "status" : "confirmed" , "confirmation" : { "confirmation_number" : "0x7a3b...1a2b" , "receipt_url" : "https://sepolia.basescan.org/tx/0x7a3b...1a2b" , "confirmation_email_sent" : true }, "line_items" : [ { "product_id" : "prod_socks_001" , "variant_id" : "var_socks_blk_m" , "title" : "Classic Crew Socks - Black / M" , "quantity" : 1 , "unit_price" : { "amount" : 1299 , "currency" : "usd" } } ], "totals" : { "subtotal" : 1299 , "tax" : 104 , "shipping" : 599 , "total" : 2002 } } }
The socks are ordered. 20.02 USDC has settled on-chain to the merchant’s wallet on Base Sepolia.
Testing Use the Prism gateway with your own account and small amounts to validate the full flow end-to-end against real on-chain settlement.
Merchant Guide Step-by-step implementation for the merchant server
Agent Guide Step-by-step implementation for the agent
