> ## 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. Asynchronous — returns `200 OK` with an
empty body; track progress via webhooks.

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

**Webhooks:** because the response body is empty, register a `swap_updated` webhook
(via `POST /ramp/webhook`) to receive `SwapResponse` payloads as the swap
progresses: `swap_created → swap_funded → swap_completed` (or `swap_failed`).



## OpenAPI

````yaml /openapi.json post /ramp/swap
openapi: 3.1.0
info:
  title: Etherfuse FX API
  description: Partner-facing ramp API for onramps, offramps, swaps, and KYC.
  license:
    name: Proprietary
  version: 1.0.0
servers:
  - url: https://api.sand.etherfuse.com
    description: Sandbox
security:
  - ApiKeyAuth: []
tags:
  - name: Authentication
    description: >-
      Partner JWT authentication — exchange a JWT for an access token, or launch
      a user into the app.
  - name: Lookup
    description: >-
      Public reference data: exchange rates, stablebonds, bond costs, country
      codes.
  - name: Assets
    description: Rampable stablecoins and stablebonds available per blockchain.
  - name: Onboarding
    description: Hosted and programmatic customer onboarding.
  - name: Agreements
    description: Legal agreement acceptance during onboarding.
  - name: Bank Accounts
    description: Register and retrieve customer bank accounts.
  - name: Quotes
    description: Price quotes for onramps, offramps, and swaps.
  - name: Orders
    description: Create, track, and manage ramp orders.
  - name: Swaps
    description: Crypto-to-crypto swaps.
  - name: Sponsored
    description: Token approvals for sponsored (gasless) offramps.
  - name: Customers
    description: Customer (child-organization) records.
  - name: Wallets
    description: Register and manage customer wallets.
  - name: KYC
    description: Submit and check customer KYC status.
  - name: Webhooks
    description: Event notification subscriptions.
  - name: Organizations
    description: Organization identity, child orgs, and partner fees.
paths:
  /ramp/swap:
    post:
      tags:
        - Swaps
      summary: Swap assets
      description: >-
        Swaps two different crypto assets. Asynchronous — returns `200 OK` with
        an

        empty body; track progress via webhooks.


        **Flow:**

        1. Call `POST /ramp/quote` with `quoteAssets.type: "swap"` to get
        pricing.

        2. Call this endpoint with the returned `quoteId` to initiate the swap.

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


        **Webhooks:** because the response body is empty, register a
        `swap_updated` webhook

        (via `POST /ramp/webhook`) to receive `SwapResponse` payloads as the
        swap

        progresses: `swap_created → swap_funded → swap_completed` (or
        `swap_failed`).
      operationId: swap
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSwapPayload'
        required: true
      responses:
        '200':
          description: Swap accepted; track completion via `swap_updated` webhooks
        '400':
          description: Invalid request or missing/expired quote
components:
  schemas:
    CreateSwapPayload:
      type: object
      description: Request body for initiating an asset swap from a `swap`-type quote.
      required:
        - orderId
        - quoteId
        - publicKey
        - blockchain
      properties:
        blockchain:
          $ref: '#/components/schemas/Blockchain'
          description: Blockchain the swap executes on.
        orderId:
          type: string
          format: uuid
          description: Client-generated order ID (UUID) for this swap.
        publicKey:
          type: string
          description: Customer's wallet public key on `blockchain`.
        quoteId:
          type: string
          format: uuid
          description: >-
            Quote ID from a prior `/ramp/quote` call made with
            `quoteAssets.type: "swap"`.
        targetWallet:
          type:
            - string
            - 'null'
          description: Optional destination wallet; defaults to `publicKey` when omitted.
      example:
        blockchain: solana
        orderId: 9c7b3f1a-2e4d-4b6a-8c1d-0f9e8d7c6b5a
        publicKey: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN
        quoteId: 3f2a1b0c-9d8e-7f6a-5b4c-3d2e1f0a9b8c
        targetWallet: null
    Blockchain:
      type: string
      description: |-
        Canonical blockchain enum for API serialization.
        Use this type for JSON APIs and WebSocket messages.
        For database storage, convert to `BlockchainType`.
      enum:
        - stellar
        - solana
        - base
        - polygon
        - monad
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key sent in the Authorization header.

````