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

# Swap assets

> Swaps two different crypto assets. This endpoint is asynchronous and returns an HTTP 200 OK with an empty body.

**Flow:**
1. First, call `/ramp/quote` with `quoteAssets.type: "swap"` to get pricing
2. Then, call this endpoint with the `quoteId` to initiate the swap
3. Listen for `swap_updated` webhook events to track swap progress and receive the transaction to sign

**Webhook Response:** Since this endpoint returns an empty body, you must use webhooks to receive swap updates. Register a webhook for the `swap_updated` event type via [POST /ramp/webhook](/api-reference/webhooks/create-webhook) to receive `SwapResponse` payloads as the swap progresses through statuses: `swap_created` → `swap_funded` → `swap_completed` (or `swap_failed`).

See the [Webhooks documentation](/api-reference/webhooks/create-webhook) for setup instructions and the webhook payload structure below.




## OpenAPI

````yaml /openapi.yaml post /ramp/swap
openapi: 3.1.0
info:
  title: FX API
  version: 1.0.0
  description: >
    API for managing FX operations including onboarding, quotes, orders, and
    customer management.

    This API provides endpoints for managing customers, bank accounts, crypto
    wallets, orders, and webhooks.
servers:
  - url: https://api.etherfuse.com
    description: Production API
  - url: https://api.sand.etherfuse.com
    description: Sandbox API (for testing)
security: []
tags:
  - name: Lookup
    description: Public endpoints for looking up stablebond and exchange rate data
  - name: Assets
    description: Get available assets for ramping
  - name: Onboarding
    description: Customer onboarding and KYC
  - name: Bank Accounts
    description: Manage customer bank accounts
  - name: Agreements
    description: Handle customer agreements and consents
  - name: Quotes
    description: Get quotes for conversions
  - name: Orders
    description: Create and manage orders
  - name: Swaps
    description: Create and manage swaps
  - name: Customers
    description: Manage customers
  - name: Crypto Wallets
    description: Manage crypto wallets
  - name: Webhooks
    description: Manage webhook subscriptions
  - name: Organizations
    description: Manage organizations and child organizations
paths:
  /ramp/swap:
    post:
      tags:
        - Swap
      summary: Swap assets
      description: >
        Swaps two different crypto assets. This endpoint is asynchronous and
        returns an HTTP 200 OK with an empty body.


        **Flow:**

        1. First, call `/ramp/quote` with `quoteAssets.type: "swap"` to get
        pricing

        2. Then, call this endpoint with the `quoteId` to initiate the swap

        3. Listen for `swap_updated` webhook events to track swap progress and
        receive the transaction to sign


        **Webhook Response:** Since this endpoint returns an empty body, you
        must use webhooks to receive swap updates. Register a webhook for the
        `swap_updated` event type via [POST
        /ramp/webhook](/api-reference/webhooks/create-webhook) to receive
        `SwapResponse` payloads as the swap progresses through statuses:
        `swap_created` → `swap_funded` → `swap_completed` (or `swap_failed`).


        See the [Webhooks documentation](/api-reference/webhooks/create-webhook)
        for setup instructions and the webhook payload structure below.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwapPayload'
      responses:
        '200':
          description: >
            Swap initiated successfully. The response body is empty.


            Subscribe to `swap_updated` webhooks to receive swap progress
            updates with the following payload:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwapResponse'
              example:
                orderId: 123e4567-e89b-12d3-a456-426614174000
                customerId: 34fcc67a-2454-4578-8435-e2bf03b4dc30
                sendTransaction: AQAAAA...encoded_tx
                sendTransactionHash: ''
                status: created
                createdAt: '2025-01-15T10:00:00Z'
                updatedAt: '2025-01-15T10:00:00Z'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    SwapPayload:
      type: object
      properties:
        orderId:
          type: string
          format: uuid
          description: Order ID for the swap (generated by the client)
        quoteId:
          type: string
          format: uuid
          description: Quote ID to use for the swap
        publicKey:
          type: string
          description: Source wallet public key for the swap
        blockchain:
          type: string
          enum:
            - stellar
            - solana
            - base
            - polygon
            - monad
          description: Blockchain type for the swap
        targetWallet:
          type: string
          nullable: true
          description: >-
            Target wallet address for the swap. If not provided, defaults to
            publicKey.
      required:
        - orderId
        - quoteId
        - publicKey
        - blockchain
      example:
        orderId: 123e4567-e89b-12d3-a456-426614174000
        quoteId: 844393ca-be57-4817-a58a-5b60e2792c06
        publicKey: GDUKMGUGD3V6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWL
        blockchain: stellar
    SwapResponse:
      type: object
      description: >
        Swap response payload sent via the `swap_updated` webhook.

        This is not returned directly from the POST /ramp/swap endpoint (which
        returns an empty body).
      properties:
        orderId:
          type: string
          format: uuid
          description: Unique identifier for the swap order
        customerId:
          type: string
          format: uuid
          description: ID of the customer who initiated the swap
        sendTransaction:
          type: string
          description: Encoded transaction for the user to sign and submit
        sendTransactionHash:
          type: string
          description: Transaction hash of the send transaction once submitted
        receiveTransactionHash:
          type: string
          nullable: true
          description: Transaction hash of the receive transaction (if applicable)
        status:
          type: string
          enum:
            - created
            - funded
            - completed
            - failed
          description: Current status of the swap
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the swap was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the swap was last updated
      required:
        - orderId
        - customerId
        - sendTransaction
        - sendTransactionHash
        - status
        - createdAt
        - updatedAt
      example:
        orderId: 123e4567-e89b-12d3-a456-426614174000
        customerId: 34fcc67a-2454-4578-8435-e2bf03b4dc30
        sendTransaction: AQAAAA...encoded_tx
        sendTransactionHash: 3Kz8V2x...abc123
        receiveTransactionHash: 4Lz9W3y...def456
        status: completed
        createdAt: '2025-01-15T10:00:00Z'
        updatedAt: '2025-01-15T10:05:00Z'
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      example:
        error: Invalid request parameters
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key for authentication. Pass the key directly (e.g., `Authorization:
        your-api-key`). Do not use a `Bearer` prefix.

````