> ## 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.

# Commerce Payments

> Agent Wallet handles the payment layer for UCP and x402 commerce. Declare support in your profile, and the wallet signs when it's time to pay.

Agent Wallet plugs into two commerce patterns. In both, the wallet's role is the same: sign the payment when asked.

| Pattern          | Trigger                   | What the wallet does                                                    |
| ---------------- | ------------------------- | ----------------------------------------------------------------------- |
| **x402 Paywall** | Agent hits a paid API     | Detects the 402, signs, retries automatically                           |
| **UCP Checkout** | Agent shops at a merchant | Signs the x402 authorization when the agent requests it during checkout |

Everything else (discovering merchants, browsing catalogs, creating checkout sessions, submitting the credential) is handled by the agent or its platform. This page covers only the parts where Agent Wallet enters.

## Declare the Handler

For UCP merchants to know your agent can pay via Prism, your platform's UCP profile must include the `xyz.fd.prism_payment` handler.

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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"
        }
      ]
    }
  }
}
```

This tells merchants: "this agent can pay with Prism-settled stablecoins." The `spec` and `schema` point to the handler definition so the merchant can validate compatibility.

## Authorize the Payment

During a UCP checkout, the merchant returns payment requirements inside the handler's `config`: which chains, tokens, and amounts are accepted. Your agent passes this to the Agent Wallet MCP server, and the wallet:

1. Checks that the agent has sufficient balance on a supported chain
2. Selects a chain/token pair from the merchant's accepted options
3. Signs an ERC-3009 `transferWithAuthorization` inside the TEE
4. Returns the signed credential

The agent never sees private keys. The output is a self-contained x402 payment object that the agent submits back to the merchant to complete the checkout.

## x402 Paywall

When your agent requests a Prism-protected resource, the server responds with HTTP `402 Payment Required`. The wallet handles this automatically: it reads the payment requirements, signs, and retries with proof of payment. No extra work from the agent.

For more detail on the x402 protocol, see [x402 Payments](/agent-wallet/concepts/x402-payments).

## What the Wallet Handles

Across both patterns, the Agent Wallet MCP server is responsible for:

* **Payment signing** inside the TEE (private keys never leave the enclave)
* **Chain and token selection** from the merchant's accepted options
* **Balance validation** before signing
* **ERC-3009 authorization** (the x402 payment primitive)

Your agent handles the merchant interaction. The wallet handles the money.

<CardGroup cols={2}>
  <Card title="MCP Server Setup" icon="plug" href="/agent-wallet/ai-integration/mcp-server">
    Connect your agent to the wallet
  </Card>

  <Card title="UCP Merchant Integration" icon="store" href="/prism/integrations/ucp/merchants">
    The merchant side of this flow
  </Card>

  <Card title="UCP Agent Integration" icon="robot" href="/prism/integrations/ucp/agents">
    Full UCP checkout flow (protocol-level detail)
  </Card>

  <Card title="End-to-End Flow" icon="route" href="/prism/integrations/ucp/flows">
    Both sides of a complete purchase
  </Card>
</CardGroup>