> ## Documentation Index
> Fetch the complete documentation index at: https://developers.circle.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Before reading these docs, install the relevant Circle Skill to get pre-loaded context — skills are LLM-optimized and cover architecture decisions, correct flows, and common pitfalls. In Claude Code: run /plugin marketplace add circlefin/skills then /plugin install circle-skills@circle. With Vercel Skills CLI: run npx skills add circlefin/skills. Available skills: use-usdc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-usdc/SKILL.md (balances, transfers, approvals on EVM and Solana); EURC has no skill — see https://developers.circle.com/stablecoins/what-is-eurc.md; bridge-stablecoin https://github.com/circlefin/skills/blob/master/plugins/circle/skills/bridge-stablecoin/SKILL.md (crosschain transfers via CCTP, USDC, EURC, and third-party assets); use-arc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-arc/SKILL.md (Arc chain config, contract deployment, USDC bridging — Arc docs: https://docs.arc.io/llms.txt); use-circle-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-circle-wallets/SKILL.md (choose wallet type); use-developer-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-developer-controlled-wallets/SKILL.md (custodial wallets for payouts and treasury); use-user-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-user-controlled-wallets/SKILL.md (embedded wallets with Web2 login); use-modular-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-modular-wallets/SKILL.md (smart contract wallets with passkeys and ERC-4337); use-gateway https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-gateway/SKILL.md (unified USDC balance, nanopayments); use-smart-contract-platform https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-smart-contract-platform/SKILL.md (deploy, interact, monitor contracts). Pair any skill with the Circle MCP server for live SDK signatures, contract addresses, and chain IDs: {"mcpServers":{"circle":{"url":"https://api.circle.com/v1/codegen/mcp"}}}.
> Read the product overview first. Each product has an overview explaining when and why to use it. Read it before quickstarts.
> Pick the right wallet type. Developer-controlled (you hold keys), user-controlled (end user holds keys via PIN/social login), or modular (smart contract wallets with passkeys). See https://developers.circle.com/wallets.md.
> Use CCTP V2 for crosschain transfers. CCTP natively transfers USDC and EURC via burn-and-mint, and supports permissionless wrapping of third-party assets via lock-and-mint. V1 is legacy; always use V2 unless V1 is specified or the chain requires it (Noble, Sui, and Aptos still require V1). Migration guide: https://developers.circle.com/cctp/migration-from-v1-to-v2.md.
> Use Bridge Kit for frontend bridging. Wraps CCTP with a simpler SDK for user-facing apps. Use CCTP directly for backend transfers.
> Gas Station vs Paymaster. Gas Station sponsors gas for Circle Wallet transactions. Paymaster lets users pay gas in USDC. Different use cases — read both overviews.
> Gateway Nanopayments for sub-cent payments. Gasless USDC micropayments down to $0.000001 via x402 and batched settlement. For pay-per-request APIs, AI agent payments, streaming.
> Look up USDC addresses per chain. Never hardcode — use https://developers.circle.com/stablecoins/usdc-contract-addresses.md.
> Prefer SDKs over raw API calls. Node.js and Python SDKs handle auth, retries, and errors.
> API key required. Bearer token in Authorization header. Testnet and mainnet use separate keys and may use different base URLs depending on the product.
> Set up webhooks when available. Most operations are async. Webhooks deliver transaction confirmations and state changes.
> When calling list endpoints, paginate using pageSize and pageAfter until no nextPageAfter cursor is returned—stopping at the first page silently misses records.
> Building an AI agent? Start with the Agent Stack—Circle CLI, agent wallets, and nanopayments built for autonomous use cases: https://developers.circle.com/agent-stack.md.

# How-to: Manage fiat beneficiaries

> Register, check, and maintain bank account recipients for Managed Payments fiat payouts.

A beneficiary is a registered bank account recipient for fiat payouts, like an
address book entry for stablecoin payouts. Register a beneficiary for each
recipient, and wait for it to become `ACTIVE` before you send a payout to it.

## Prerequisites

Before you begin, ensure that you've:

* Enabled fiat payout permissions on your Managed Payments account.
* Created an API key with Managed Payments access from the
  [Circle hub](https://hub.circle.com).

## Steps

### Step 1. Get field requirements

The required fields vary by corridor. Call
[`GET /v1/beneficiaries/requirements`](https://developers.circle.com/api-reference/cpn/managed-payments/fiat-payouts/get-beneficiary-requirements)
with the corridor parameters and the `customerType` to get the fields you must
supply.

This example gets the requirements for an individual recipient in Mexico who is
paid over SPEI, Mexico's interbank payment system:

```bash theme={null}
curl -X GET 'https://api-sandbox.circle.com/v1/beneficiaries/requirements?destinationCountry=MX&destinationCurrency=MXN&paymentMethod=SPEI&customerType=INDIVIDUAL' \
  --header "Authorization: Bearer $API_KEY"
```

```json expandable theme={null}
{
  "data": {
    "fields": [
      {
        "name": "CLABE",
        "type": "TEXT",
        "required": true,
        "pattern": "^[0-9]{18}$",
        "validationDetails": "18 digits."
      },
      {
        "name": "BANK_NAME",
        "type": "TEXT",
        "required": false,
        "pattern": "^.{1,140}$",
        "validationDetails": "Name of the recipient's bank. Maximum 140 characters."
      },
      {
        "name": "BENEFICIARY_NAME",
        "type": "TEXT",
        "required": true,
        "pattern": "^.{1,140}$",
        "validationDetails": "Full legal name. Maximum 140 characters."
      },
      {
        "name": "BENEFICIARY_ADDRESS",
        "type": "ADDRESS",
        "required": true,
        "fields": [
          { "name": "STREET", "type": "TEXT", "required": true },
          { "name": "CITY", "type": "TEXT", "required": true },
          { "name": "STATE_PROVINCE", "type": "TEXT", "required": false },
          { "name": "POSTAL_CODE", "type": "TEXT", "required": true },
          { "name": "COUNTRY", "type": "TEXT", "required": true }
        ]
      }
    ]
  }
}
```

In the registration request, send the fields in two objects, split by field
name:

* `travelRule`: fields that start with `BENEFICIARY_`, such as
  `BENEFICIARY_NAME` and `BENEFICIARY_ADDRESS`. These are the recipient details
  the Travel Rule requires.
* `bankAccount`: all other fields, such as `CLABE`, `IBAN`, and
  `ACCOUNT_NUMBER`.

### Step 2. Register a beneficiary

> [!WARNING]
>
> You can't update a beneficiary. To fix an error, delete it and register it again
> with the corrected details. Use the new beneficiary ID in your payout requests.

Send the fields from Step 1 to
[`POST /v1/beneficiaries`](https://developers.circle.com/api-reference/cpn/managed-payments/fiat-payouts/create-beneficiary).
This example registers an individual SPEI beneficiary in Mexico:

```bash expandable theme={null}
curl -X POST 'https://api-sandbox.circle.com/v1/beneficiaries' \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "idempotencyKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customerType": "INDIVIDUAL",
    "destinationCountry": "MX",
    "destinationCurrency": "MXN",
    "paymentMethod": "SPEI",
    "bankAccount": {
      "CLABE": "012345678901234567",
      "BANK_NAME": "BBVA Mexico"
    },
    "travelRule": {
      "BENEFICIARY_NAME": "Alice Garcia",
      "BENEFICIARY_ADDRESS": {
        "STREET": "Av. Reforma 100",
        "CITY": "Ciudad de Mexico",
        "STATE_PROVINCE": "CDMX",
        "POSTAL_CODE": "06600",
        "COUNTRY": "MX"
      }
    }
  }'
```

The response returns `201`. The `status` is `INACTIVE` while Circle screens the
beneficiary:

```json theme={null}
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customerType": "INDIVIDUAL",
    "destinationCountry": "MX",
    "destinationCurrency": "MXN",
    "paymentMethod": "SPEI",
    "status": "INACTIVE"
  }
}
```

Save the `id`. You use it as the `destination.id` when you send a payout.

### Step 3. Wait for the beneficiary to become active

Circle screens the beneficiary in the background, and you can't send a payout to
it until its status is `ACTIVE`. Subscribe to the
[`payouts.beneficiary.updated`](https://developers.circle.com/api-reference/cpn/managed-payments/webhooks/payouts-beneficiary-updated)
webhook event to learn when screening finishes. To set up your endpoint, see
[Set up a webhook endpoint](https://developers.circle.com/api-reference/webhook-endpoints.md#v2-notifications).
To secure it, see [Webhook security](https://developers.circle.com/cpn/concepts/webhooks/webhook-security.md).

If you can't receive webhooks, such as when testing without a public endpoint,
poll
[`GET /v1/beneficiaries/{id}`](https://developers.circle.com/api-reference/cpn/managed-payments/fiat-payouts/get-beneficiary)
until `status` changes from `INACTIVE`:

```bash theme={null}
curl -X GET 'https://api-sandbox.circle.com/v1/beneficiaries/{id}' \
  --header "Authorization: Bearer $API_KEY"
```

```json theme={null}
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "ACTIVE",
    "customerType": "INDIVIDUAL",
    "destinationCountry": "MX",
    "destinationCurrency": "MXN",
    "paymentMethod": "SPEI"
  }
}
```

If `status` is `DENIED`, screening rejected the beneficiary. Delete it and
register a new one.

## Manage existing beneficiaries

### List beneficiaries

Call
[`GET /v1/beneficiaries`](https://developers.circle.com/api-reference/cpn/managed-payments/fiat-payouts/list-beneficiaries)
to retrieve your beneficiaries. Use the `status` query parameter to filter the
results, and `pageSize`, `pageAfter`, and `pageBefore` to page through them.

```bash theme={null}
curl -X GET 'https://api-sandbox.circle.com/v1/beneficiaries?status=ACTIVE' \
  --header "Authorization: Bearer $API_KEY"
```

### Delete a beneficiary

Call
[`DELETE /v1/beneficiaries/{id}`](https://developers.circle.com/api-reference/cpn/managed-payments/fiat-payouts/delete-beneficiary)
to delete a beneficiary. Circle permanently removes the recipient's personal
data, and `GET /v1/beneficiaries/{id}` returns `404` afterward. Deleting a
beneficiary that's already deleted also succeeds.

```bash theme={null}
curl -X DELETE 'https://api-sandbox.circle.com/v1/beneficiaries/{id}' \
  --header "Authorization: Bearer $API_KEY"
```

A successful delete returns `204 No Content`.

### Recover a stale beneficiary

If a corridor's required fields change after you register a beneficiary, its
status becomes `STALE` and it can't receive payouts. To recover, call
`GET /v1/beneficiaries/requirements` for the current fields, delete the
beneficiary, and register it again.

To send a fiat payout using an `ACTIVE` beneficiary, see
[Send fiat payouts](https://developers.circle.com/cpn/managed-payments/quickstarts/send-fiat-payouts.md).