Skip to main content

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.

When your agent finds a UCP merchant that supports xyz.fd.prism_payment, it can pay with any x402-capable wallet. This page covers the four steps: discover, checkout, sign, and complete.

​
Prerequisites

  • An x402-capable wallet funded on a supported chain
  • A UCP profile your agent can reference (e.g., https://platform.example/ucp/profile)
If your platform uses the Finance District Agent Wallet, x402 signing is handled automatically by the MCP server. See Agent Wallet MCP Server. Include xyz.fd.prism_payment in your platform’s payment_handlers registry with spec and schema. No config is needed. This tells the merchant your platform can fulfill this payment method. 
{
  "ucp": {
    "version": "2026-01-23",
    "payment_handlers": {
      "xyz.fd.prism_payment": [
        {
          "id": "prism_default",
          "version": "2026-01-23",
          "spec": "https://prism-gw.fd.xyz/ucp/prism.md",
          "schema": "https://prism-gw.fd.xyz/ucp/schema.json"
        }
      ]
    }
  }
}

​
Payment Flow

​
Step 1: Discover the Handler

GET https://merchant.example/.well-known/ucp
Confirm xyz.fd.prism_payment appears in payment_handlers. If present, the merchant accepts Prism payments and the flow can proceed.

​
Step 2: Create a Checkout Session

POST https://merchant.example/checkout-sessions
Content-Type: application/json
UCP-Agent: profile="https://platform.example/ucp/profile"

{
  "line_items": [
    { "item": { "id": "ticket_vip_01" }, "quantity": 1 }
  ]
}
The response contains payment_handlers["xyz.fd.prism_payment"][0].config — the x402 payment requirements populated by Prism. Extract this object; it is the direct input for wallet authorization.

​
Step 3: Authorize with Your Wallet

Pass the config object to your x402-capable wallet as paymentRequirements. The wallet selects a network from accepts, signs an ERC-3009 authorization inside the secure enclave, and returns the complete signed payment object. The Finance District Agent Wallet handles this via its x402 authorization tool. Pass the config directly and it returns the signed object ready for submission — no additional formatting required.

​
Step 4: Complete the Checkout

Submit the wallet output as the credential. Both instrument.type and credential.type must be "default" — they are required UCP schema discriminators for this handler. 
POST https://merchant.example/checkout-sessions/{id}/complete
Content-Type: application/json
UCP-Agent: profile="https://platform.example/ucp/profile"

{
  "payment": {
    "instruments": [
      {
        "id": "your_instrument_id",
        "handler_id": "prism_default",
        "type": "default",
        "credential": {
          "type": "default",
          "paymentPayload": { "...": "signed ERC-3009 authorization" },
          "paymentRequirements": { "...": "config from Step 2" }
        }
      }
    ]
  }
}
A successful response returns a confirmed order with an on-chain transaction hash: 
{
  "order": {
    "id": "ord_abc123",
    "status": "confirmed",
    "payment": {
      "handler_id": "prism_default",
      "status": "settled",
      "transaction": "0xe80c...674b"
    }
  }
}

Commerce Payments

How Agent Wallet handles the payment signing

Agent Wallet MCP Server

Connect your agent to the Finance District wallet via MCP

End-to-End Flow

See the full purchase cycle with both sides visible
Last modified on March 24, 2026