curl --request POST \
  --url https://production.hifi.com/v3/swaps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "requestId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "limitPrice": "0.9990",
  "cancelAfterSeconds": 3600,
  "source": {
    "walletId": "wlt_3Kf9dQ2mNpXwZ7bV1aLcs",
    "currency": "USDC",
    "amount": 100
  },
  "destination": {
    "walletId": "wlt_7bV1aLcs3Kf9dQ2mNpXwZ",
    "currency": "USDT"
  }
}
'

{
  "id": "swap_7bV1aLcs3Kf9dQ2mNpXwZ",
  "requestId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "OPEN_QUOTE",
  "error": null,
  "errorDetails": null,
  "amount": "100",
  "source": {
    "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
    "walletId": "wlt_3Kf9dQ2mNpXwZ7bV1aLcs",
    "currency": "USDC",
    "chain": "POLYGON"
  },
  "destination": {
    "userId": "usr_7bV1aLcs3Kf9dQ2mNpXwZ",
    "walletId": "wlt_7bV1aLcs3Kf9dQ2mNpXwZ",
    "externalWalletId": null,
    "currency": "USDT",
    "chain": "POLYGON"
  },
  "receipt": {
    "transactionHash": null
  },
  "quote": {
    "sendGross": {
      "amount": "100",
      "currency": "USDC"
    },
    "sendNet": {
      "amount": "100",
      "currency": "USDC"
    },
    "receiveGross": {
      "amount": "100",
      "currency": "USDT"
    },
    "receiveNet": {
      "amount": "100",
      "currency": "USDT"
    },
    "rate": "1.0",
    "expiresAt": "2026-07-01T10:35:00.000Z"
  },
  "createdAt": "2026-07-01T10:30:00.000Z",
  "updatedAt": "2026-07-01T10:30:00.000Z"
}

{
  "type": "VALIDATION_ERROR",
  "message": "One or more fields are invalid or missing.",
  "fields": [
    {
      "code": "invalid_value",
      "message": "Must be a valid email address",
      "field": "email"
    }
  ]
}

{
  "type": "UNAUTHORIZED",
  "message": "Authentication required"
}

{
  "type": "RESOURCE_CONFLICT",
  "message": "Resource already exists or conflicts with current state"
}

{
  "type": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred"
}

Swaps

Create a swap

Create a token swap. A swap exchanges one stablecoin for another between a source wallet and a destination wallet (owned by a user or an external wallet).

The source and destination currency must be different. Provide exactly one of source.amount or destination.amount — the other side is derived from the quote. Provide exactly one of destination.walletId or destination.externalWalletId.

Depending on the pricing model, the swap may be created directly or returned in an OPEN_QUOTE state that must be accepted before execution.

POST

swaps

curl --request POST \
  --url https://production.hifi.com/v3/swaps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "requestId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "limitPrice": "0.9990",
  "cancelAfterSeconds": 3600,
  "source": {
    "walletId": "wlt_3Kf9dQ2mNpXwZ7bV1aLcs",
    "currency": "USDC",
    "amount": 100
  },
  "destination": {
    "walletId": "wlt_7bV1aLcs3Kf9dQ2mNpXwZ",
    "currency": "USDT"
  }
}
'

{
  "id": "swap_7bV1aLcs3Kf9dQ2mNpXwZ",
  "requestId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "OPEN_QUOTE",
  "error": null,
  "errorDetails": null,
  "amount": "100",
  "source": {
    "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
    "walletId": "wlt_3Kf9dQ2mNpXwZ7bV1aLcs",
    "currency": "USDC",
    "chain": "POLYGON"
  },
  "destination": {
    "userId": "usr_7bV1aLcs3Kf9dQ2mNpXwZ",
    "walletId": "wlt_7bV1aLcs3Kf9dQ2mNpXwZ",
    "externalWalletId": null,
    "currency": "USDT",
    "chain": "POLYGON"
  },
  "receipt": {
    "transactionHash": null
  },
  "quote": {
    "sendGross": {
      "amount": "100",
      "currency": "USDC"
    },
    "sendNet": {
      "amount": "100",
      "currency": "USDC"
    },
    "receiveGross": {
      "amount": "100",
      "currency": "USDT"
    },
    "receiveNet": {
      "amount": "100",
      "currency": "USDT"
    },
    "rate": "1.0",
    "expiresAt": "2026-07-01T10:35:00.000Z"
  },
  "createdAt": "2026-07-01T10:30:00.000Z",
  "updatedAt": "2026-07-01T10:30:00.000Z"
}

{
  "type": "VALIDATION_ERROR",
  "message": "One or more fields are invalid or missing.",
  "fields": [
    {
      "code": "invalid_value",
      "message": "Must be a valid email address",
      "field": "email"
    }
  ]
}

{
  "type": "UNAUTHORIZED",
  "message": "Authentication required"
}

{
  "type": "RESOURCE_CONFLICT",
  "message": "Resource already exists or conflicts with current state"
}

{
  "type": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Swap details. Source and destination currencies must differ, exactly one of source.amount / destination.amount must be provided, and exactly one of destination.walletId / destination.externalWalletId must be provided.

Swap creation payload. Source and destination currencies must differ, exactly one of source.amount / destination.amount must be set, and exactly one of destination.walletId / destination.externalWalletId must be set.

requestId

string<uuid>

required

Client-generated idempotency key. A UUID unique to this swap request.

Example:

"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"

source

object

required

Source of the swap.

Show child attributes

destination

object

required

Destination of the swap. Provide exactly one of walletId or externalWalletId.

Show child attributes

limitPrice

string

Optional destination units per source unit for a direct USDC/USDT swap. Sandbox validates and returns this value but does not delay simulated execution for it.

Pattern: ^(?=.*[1-9])\d+(?:\.\d{1,4})?$

Example:

"0.9990"

cancelAfterSeconds

integer

Optional cancellation deadline in seconds for a direct USDC/USDT swap.

Required range: 60 <= x <= 86400

Example:

3600

Response

Swap created successfully.

A token swap.

string

Public ID of the swap (prefixed with swap_).

Example:

"swap_7bV1aLcs3Kf9dQ2mNpXwZ"

requestId

string<uuid>

Client-generated idempotency key supplied at creation.

Example:

"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"

status

enum<string>

Available options:

DRAFT,

CREATED,

PENDING,

OPEN_QUOTE,

QUOTE_FAILED,

COMPLETED,

FAILED,

CANCELLED

Example:

"OPEN_QUOTE"

error

string | null

User-facing error summary. Null unless the swap failed or was cancelled.

Example:

null

errorDetails

string | null

User-facing error details. Null unless the swap failed or was cancelled.

Example:

null

cancellable

boolean

Whether a cancellation request can still win before execution starts.

Example:

true

autoCancelAt

string<date-time> | null

Requested automatic cancellation deadline.

Example:

"2026-07-01T11:30:00.000Z"

cancelRequestedAt

string<date-time> | null

Time manual cancellation was requested.

Example:

null

amount

string | null

Source amount of the swap.

Example:

"100"

source

object

Resolved source of the swap.

Show child attributes

destination

object

Resolved destination of the swap.

Show child attributes

receipt

object

On-chain receipt for the swap.

Show child attributes

quote

object | null

Commercial quote for the swap. Null until a quote has been generated.

Show child attributes

createdAt

string<date-time>

Example:

"2026-07-01T10:30:00.000Z"

updatedAt

string<date-time>

Example:

"2026-07-01T10:30:00.000Z"

⌘I

Overview

Endpoints

Create a swap

Authorizations

Body

Response