Agent Integration

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.

Advertise the Handler in Your Profile

Include xyz.fd.prism_payment in your platform’s payment_handlers registry. Use the same entry Prism publishes, with an empty config. This tells the merchant your platform can fulfill this payment method.

{
  "ucp": {
    "version": "2026-08-25",
    "payment_handlers": {
      "xyz.fd.prism_payment": [
        {
          "id": "xyz.fd.prism_payment",
          "version": "2026-10-07",
          "spec": "https://prism-gw.fd.xyz/ucp/prism.md",
          "schema": "https://prism-gw.fd.xyz/ucp/schema.json",
          "available_instruments": [{ "type": "x402" }],
          "config": {}
        }
      ]
    }
  }
}

The entry schema is the handler config schema. The instrument schema is linked from that document at $defs["xyz.fd.prism_payment"].instrument.

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 "x402". The credential is the wallet output plus that one type field. Set handler_id to xyz.fd.prism_payment and give the instrument an id.

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": "xyz.fd.prism_payment",
        "type": "x402",
        "credential": {
          "type": "x402",
          "x402Version": 2,
          "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": "xyz.fd.prism_payment",
      "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

Getting Started

Concepts

Architecture

Integrations

API Reference

Going to Production

AI Tooling

Resources

Prerequisites

Advertise the Handler in Your Profile

Payment Flow

Step 1: Discover the Handler

Step 2: Create a Checkout Session

Step 3: Authorize with Your Wallet

Step 4: Complete the Checkout

Commerce Payments

Agent Wallet MCP Server

End-to-End Flow

​Prerequisites

​Advertise the Handler in Your Profile

​Payment Flow

​Step 1: Discover the Handler

​Step 2: Create a Checkout Session

​Step 3: Authorize with Your Wallet

​Step 4: Complete the Checkout

Commerce Payments

Agent Wallet MCP Server

End-to-End Flow

Prerequisites

Advertise the Handler in Your Profile

Payment Flow

Step 1: Discover the Handler

Step 2: Create a Checkout Session

Step 3: Authorize with Your Wallet

Step 4: Complete the Checkout