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

# Fiat Addresses

> Register and manage bank accounts for payouts. Supports multiple payment rails including SEPA, ACH, Wire, and SWIFT.

## Overview

Fiat addresses represent bank accounts that can receive payouts from your Autoramps. Before initiating an offramp, you must register the destination bank account.

Iron supports multiple payment rails:

| Type  | Description                | Currency |
| ----- | -------------------------- | -------- |
| SEPA  | European payments via IBAN | EUR      |
| ACH   | US domestic transfers      | USD      |
| Wire  | US wire transfers          | USD      |
| RTP   | US Real-Time Payments      | USD      |
| SWIFT | International transfers    | Multiple |
| CHAPS | UK high-value payments     | GBP      |
| FPS   | UK Faster Payments         | GBP      |

## Register a bank account

Register a bank account for a customer. The request structure varies based on the payment rail.

### SEPA (Europe)

<CodeGroup>
  ```bash Bash theme={null}
  curl -X POST https://api.sandbox.iron.xyz/api/addresses/fiat \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "customer_id": "4b85d15e-f343-41c0-809c-85314cae2fa6",
    "currency": { "code": "EUR" },
    "label": "Primary Business Account",
    "bank_details": {
      "recipient": {
        "type": "Business",
        "name": "Acme Corp GmbH"
      },
      "provider_name": "Deutsche Bank",
      "provider_country": { "code": "DE" },
      "account_identifier": {
        "type": "SEPA",
        "iban": "DE89370400440532013000"
      },
      "address": {
        "street": "Crypto Street 123",
        "city": "Berlin",
        "state": "Berlin",
        "country": { "code": "DE" },
        "postal_code": "10115"
      },
      "is_third_party": false
    }
  }'
  ```
</CodeGroup>

### ACH (US Domestic)

<CodeGroup>
  ```bash Bash theme={null}
  curl -X POST https://api.sandbox.iron.xyz/api/addresses/fiat \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 123e4567-e89b-12d3-a456-426614174001" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "customer_id": "4b85d15e-f343-41c0-809c-85314cae2fa6",
    "currency": { "code": "USD" },
    "label": "Jane Doe Checking",
    "bank_details": {
      "recipient": {
        "type": "Individual",
        "given_name": "Jane",
        "family_name": "Doe"
      },
      "provider_name": "Chase Bank",
      "provider_country": { "code": "US" },
      "account_identifier": {
        "type": "ACH",
        "routing_number": "021000021",
        "account_number": "123456789012"
      },
      "address": {
        "street": "123 Main Street",
        "city": "New York",
        "state": "NY",
        "country": { "code": "US" },
        "postal_code": "10001"
      },
      "email_address": { "email": "finance@acme.com" },
      "phone_number": "+1-212-555-0123",
      "is_third_party": false
    }
  }'
  ```
</CodeGroup>

### SWIFT (International)

<CodeGroup>
  ```bash Bash theme={null}
  curl -X POST https://api.sandbox.iron.xyz/api/addresses/fiat \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 123e4567-e89b-12d3-a456-426614174002" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "customer_id": "4b85d15e-f343-41c0-809c-85314cae2fa6",
    "currency": { "code": "USD" },
    "label": "International Account",
    "bank_details": {
      "recipient": {
        "type": "Business",
        "name": "Acme Global Ltd"
      },
      "provider_name": "HSBC",
      "provider_country": { "code": "GB" },
      "account_identifier": {
        "type": "SWIFT",
        "bic": "HSBCGB2L",
        "account_number": "12345678"
      },
      "address": {
        "street": "10 Downing Street",
        "city": "London",
        "state": "England",
        "country": { "code": "GB" },
        "postal_code": "SW1A 2AA"
      },
      "bank_address": {
        "street": "8 Canada Square",
        "city": "London",
        "country": { "code": "GB" },
        "postal_code": "E14 5HQ"
      },
      "is_third_party": false
    }
  }'
  ```
</CodeGroup>

<Note>
  SWIFT is currently available for payouts only, with originators based in the US. We are actively working toward a global solution.
</Note>

### Request fields

| Field                             | Required   | Description                                                                                                             |
| --------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| `customer_id`                     | Yes        | The customer's UUID                                                                                                     |
| `currency`                        | Yes        | Object with a `code` property (e.g. `{ "code": "EUR" }`)                                                                |
| `label`                           | No         | Optional label for the account                                                                                          |
| `bank_details.recipient`          | Yes        | Object with a `type` discriminator. `Business`: requires `name`. `Individual`: requires `given_name` and `family_name`. |
| `bank_details.provider_name`      | Yes        | Bank name                                                                                                               |
| `bank_details.provider_country`   | Yes        | Bank's country as `{ "code": "<ISO 3166-1>" }`                                                                          |
| `bank_details.account_identifier` | Yes        | Account details (varies by payment rail)                                                                                |
| `bank_details.address`            | Yes        | Recipient's postal address. All fields including `state` are required.                                                  |
| `bank_details.email_address`      | USD only   | Required for USD accounts                                                                                               |
| `bank_details.phone_number`       | USD only   | Required for USD accounts                                                                                               |
| `bank_details.is_third_party`     | Yes        | Whether this is a third-party account                                                                                   |
| `bank_details.bank_address`       | SWIFT only | Required for SWIFT transfers                                                                                            |

### Response

<CodeGroup>
  ```json JSON theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z",
    "customer_id": "4b85d15e-f343-41c0-809c-85314cae2fa6",
    "bank_details": { ... },
    "label": "Primary Business Account",
    "status": "Registered",
    "currency": "EUR",
    "bank_account_identifier": {
      "type": "SEPA",
      "iban": "DE89XXXXXXXXXXXX3000"
    },
    "country": "DE",
    "bank_name": "Deutsche Bank",
    "ownership_verified": true,
    "is_third_party": false
  }
  ```
</CodeGroup>

<Note>
  The `bank_account_identifier` in the response is partially masked for security.
</Note>

## List bank accounts

Retrieve all registered bank accounts for a customer:

<CodeGroup>
  ```bash Bash theme={null}
  curl -X GET "https://api.sandbox.iron.xyz/api/addresses/fiat/{customer_id}" \
  -H "X-API-Key: $API_KEY"
  ```
</CodeGroup>

### Query parameters

| Parameter     | Description                              |
| ------------- | ---------------------------------------- |
| `cursor`      | Pagination cursor from previous response |
| `page_size`   | Number of results per page (max 100)     |
| `search_term` | Filter by IBAN, label, or bank name      |

### List by status

Retrieve all bank accounts with a specific status across all customers:

<CodeGroup>
  ```bash Bash theme={null}
  curl -X GET "https://api.sandbox.iron.xyz/api/addresses/fiat?status=Registered" \
  -H "X-API-Key: $API_KEY"
  ```
</CodeGroup>

## Get a specific bank account

<CodeGroup>
  ```bash Bash theme={null}
  curl -X GET "https://api.sandbox.iron.xyz/api/addresses/fiat/{customer_id}/{fiat_address_id}" \
  -H "X-API-Key: $API_KEY"
  ```
</CodeGroup>

## Delete a bank account

Soft-delete a registered bank account:

<CodeGroup>
  ```bash Bash theme={null}
  curl -X DELETE "https://api.sandbox.iron.xyz/api/addresses/fiat/{customer_id}/{fiat_address_id}" \
  -H "X-API-Key: $API_KEY"
  ```
</CodeGroup>

<Note>
  Deleted accounts cannot be used for new transactions. This operation cannot be undone.
</Note>

## Address statuses

Beneficiary whitelisting is instant. There is no separate recipient verification step. Most accounts move from `RegistrationPending` to `Registered` within seconds. If they don't, the status tells you why.

| Status                  | Description                                                                                                                                                         |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RegistrationPending`   | Registration in progress. Resolves within seconds in production.                                                                                                    |
| `Registered`            | Account is active and ready for payouts.                                                                                                                            |
| `RegistrationFailed`    | The bank details were rejected. Common causes: invalid IBAN or routing number, mismatched recipient name, missing required fields. Fix the details and re-register. |
| `AuthorizationRequired` | In rare cases the beneficiary needs to be approved by the bank before payouts can run.                                                                              |
| `AuthorizationFailed`   | The beneficiary was rejected by compliance. The account cannot receive payouts.                                                                                     |

## Third-party accounts

To register a bank account that doesn't belong to the customer (a friend, family member, or business counterparty), set `is_third_party: true`. The registration flow is identical to first-party accounts: beneficiary whitelisting is instant, and the account is ready for payouts within seconds.

## Common errors

| Error             | Cause                                                            |
| ----------------- | ---------------------------------------------------------------- |
| `400 Bad Request` | Invalid IBAN format, missing required fields, or invalid country |
| `404 Not Found`   | Customer not found or does not belong to your partner            |
| `409 Conflict`    | Bank account already registered for this customer                |

## Related guides

<CardGroup>
  <Card title="Crypto Addresses" href="/crypto-addresses" icon="wallet" horizontal />

  <Card title="Offramp Guide" href="/offramp" icon="arrow-down" horizontal />
</CardGroup>