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

# Swap

> Swap one stablecoin for another across chains using autoramp rules. Examples: USDC on Solana to EURC on Ethereum, USDT to USDC.

## Use Case

Enable users to swap **token 1 into token 2** across various chains.

Examples:

* Setup wallet address 1 which turns incoming **USDC on Solana into EURC on Arbitrum**
* Setup wallet address 2 which turns incoming **SOL on Solana into USDC on Arbitrum**

## Example Flow

<Steps>
  <Step>
    User sets up a **wallet address 1** on Solana owned by Iron
  </Step>

  <Step>
    Now an `autoramp` is activated

    i. which turns all incoming USDC on wallet address 1 into EURC on Arbitrum

    ii. and delivers those into his connected wallet in **wallet address 2**
  </Step>

  <Step>
    Now user sends 1000 USDC to **wallet address 1**
  </Step>

  <Step>
    As soon as funds hit this address, Iron turns them into EURC on Arbitrum and delivers them to **wallet address 2**
  </Step>
</Steps>

This flow lets applications add bridging and automatic swaps without users stepping through multi-step UIs. Any wallet or frontend can integrate it with one API call.

## Prerequisites

Every step must complete before moving to the next. Sandbox-only steps are marked.

<Steps>
  <Step title="Customer is Active">
    Your customer must have `Active` status. This means they have completed [identification](/onboarding) (KYC/KYB) and signed all required documents.
  </Step>

  <Step title="Register the recipient wallet address">
    Register the destination wallet via [Crypto Addresses](/crypto-addresses) for [Travel Rule](/travel-rule) compliance. Self-hosted wallets require a signed proof-of-ownership message; hosted wallets require the custodian's DID.

    The wallet you pass in `recipient_account` must match an address you have already registered for this customer.
  </Step>

  <Step title="(Optional) Get a quote">
    If you need a locked rate (and lower-bps fee profiles), request a quote via `GET /autoramps/quote`. See [Quotes](/quotes). Otherwise, the swap executes at the current mid-market rate.

    Standalone swap autoramps cannot attach quotes later. If you anticipate needing locked rates over time, start with a quote-source autoramp.
  </Step>

  <Step title="Create the swap autoramp">
    Create the autoramp via `POST /autoramps` using the registered wallet address as the recipient. See the Implementation example below.
  </Step>

  <Step title="Sandbox: approve the autoramp">
    In Sandbox, the autoramp starts in `Authorized` status. Approve it to enable transaction processing:

    ```bash theme={null}
    curl -X PUT "https://api.sandbox.iron.xyz/api/sandbox/autoramp/<autoramp_id>" \
      -H "Content-Type: application/json" \
      -H "X-API-Key: $API_KEY" \
      -d '"Approved"'
    ```

    In production, autoramps are approved automatically after compliance review.
  </Step>
</Steps>

## Implementation

Follow these example steps to create an autoramp logic for turning USDC on Solana to EURC on Arbitrum.

### Request

<CodeGroup>
  ```bash Shell theme={null}
  curl -X POST "https://api.sandbox.iron.xyz/api/autoramps" \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "IDEMPOTENCY-KEY: <your-idempotency-key>" \
    -H "X-API-Key: <your-api-key>" \
    -d '{
      "source_currencies": [{
        "type": "Crypto",
        "token": "USDC",
        "blockchain": "Solana"
      }],
      "destination_currency": {
        "type": "Crypto",
        "token": "EURC",
        "blockchain": "Arbitrum"
      },
      "recipient_account": {
        "type": "Crypto",
        "chain": "Arbitrum",
        "address": "0xaf77d065e77c8cC2239327C5EDb3A432268e5831"
      },
      "customer_id": "123e4567-e89b-12d3-a456-426614174000",
      "source_is_third_party": false
    }'
  ```
</CodeGroup>

<Note>
  `POST /api/autoramps` requires an `IDEMPOTENCY-KEY` header. Use a unique UUID per request to prevent duplicate autoramps.
</Note>

### Response

<CodeGroup>
  ```json 200 Authorized theme={null}
  {
    "id": "d4e3c2b1-a9f8-7654-3210-fedcba987654",
    "customer_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "Authorized",
    "kind": "Swap",
    "source": "Standalone",
    "source_currencies": [
      {
        "type": "Crypto",
        "token": "USDC",
        "blockchain": "Solana"
      }
    ],
    "destination_currency": {
      "type": "Crypto",
      "token": "EURC",
      "blockchain": "Arbitrum"
    },
    "recipient": {
      "type": "Wallet",
      "blockchain": "Arbitrum",
      "address": "0xaf77d065e77c8cC2239327C5EDb3A432268e5831"
    },
    "is_third_party": false,
    "batch_payout": false,
    "fee_profile_id": "9b2e7c14-5f3a-4d8b-b1c6-2a4e6f8d0c12",
    "quotes": [],
    "deposit_rails": [],
    "created_at": "2025-01-20T14:23:45Z"
  }
  ```

  ```json 422 Unprocessable Entity theme={null}
  {
    "message": "Recipient wallet 0xaf77d065e77c8cC2239327C5EDb3A432268e5831 on Arbitrum is not registered for this customer. Register it via /api/crypto-addresses before creating the autoramp.",
    "trace_id": "b7c4f2e1-9a3d-4e8c-bf12-6d5a0c3e7b94"
  }
  ```
</CodeGroup>

<Note>
  `deposit_rails` is empty at `Authorized`. Poll `GET /autoramps/{id}` or subscribe to webhooks until `status = Approved` before sharing deposit details with end users. See [Autoramp Status](/autoramp-status).
</Note>

Once the autoramp reaches `Approved`, the response includes the deposit wallet address under `deposit_rails`. Share it with the user along with the supported assets for that wallet (e.g. EURC, USDC). Non-supported assets sent to the wallet will be returned to sender.