Ctrlk
Go to website
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Swap

Create a swap order (POST /v1/swap)

Create a swap order

post
/v1/swap

Creates an order with the chosen provider. No JWT is required. Optional header x-api-key-partner attributes the order to a partner; an invalid key returns 401 INVALID_API_KEY.

NestJS default status for this POST is 201 Created.

engine (must be one of cex | dex | private):

  • cex — off-chain. Send funds to depositAddress (memo: extraIdDeposit when present).

  • dex — on-chain. depositAddress is typically null; follow txCreateMeta / provider payload.

  • private — two-rail. No Bearer token is checked. Send funds to depositAddress. quoteId is passed to the private workflow as routeId.

Rate snapshot (rateId) — UUID from GET /v1/quote. If sent:

  • missing/expired snapshot → 400 RATE_EXPIRED (TTL 5 minutes)

  • provider / coin UUIDs / amount do not match the snapshot → 400 RATE_MISMATCH (error.details lists expected vs received)

quoteId is the provider quote id (rate lock) and is independent of rateId.

receiveAddress is validated against the destination token regexAddress when the catalog has one (INVALID_RECEIVE_ADDRESS). refundAddress is validated against the source token (INVALID_REFUND_ADDRESS).

addressFrom is accepted for backward compatibility and ignored.

transactionId in the response is the YiFi UUID stored in admin-service (use it on GET /v1/transactions/{id}). externalTransactionId is the provider id when it differs. accessToken is issued once — store it client-side.

Authorizations
x-api-key-partnerstringRequired

Optional partner API key on POST /v1/swap. Invalid key → 401. Omitted → anonymous swap.

Body
providerstringRequired

Provider slug from the chosen quote's provider field

Example: providerX
fromTokenstringRequired

Source token ticker

Example: ETH
fromNetworkstringRequired

Source chain slug — same as GET /v1/chains → id (case-insensitive)

Example: ETH
toTokenstringRequired

Target token ticker

Example: USDC
toNetworkstringRequired

Target chain slug — same as GET /v1/chains → id (case-insensitive)

Example: ETH
enginestring · enumRequired

Swap engine to use. Must match the engine from the selected quote.

  • cex – off-chain CEX swap

  • dex – on-chain DEX swap

  • private – two-rail private swap (no JWT required on this API)

Example: cexPossible values:
amountnumber · min: 1e-8Required

Amount to exchange in source token units

Example: 1.5
quoteIdstringOptional

Quote ID from /v1/quote. Locks in the rate with providers that support it.

Example: abc123
rateIdstringOptional

Internal rate ID from /v1/quote response. Use to record the exact quote shown to the user in the transaction history. The snapshot expires 5 minutes after the quote was issued. If you pass an expired or unknown ID the request will be rejected with RATE_EXPIRED.

Example: 4f2e6d6b-6e15-4f47-8b6e-2a3d3c5b9d10
receiveAddressstringRequired

Destination wallet address for the output token

Example: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
addressFromstringOptional

Legacy field. Accepted (not rejected by validation) but not used by createSwap.

Example: 0x1234567890abcdef1234567890abcdef12345678
slippageTolerancestringOptional

Slippage tolerance in percent. Default "0.5". Applies to DEX routes only (engine=dex). Ignored for CEX and private.

Default: 0.5Example: 0.5
extraIdTostringOptional

Memo / tag for the destination address. Required for tokens that need it (e.g. XRP, XLM, TON).

Example: 1234567890
refundAddressstringOptional

Address to receive a refund if the swap fails. Recommended when the chosen provider or route requires it — follow provider documentation and support guidance. Strongly recommended for private swaps.

Example: 0x1234567890abcdef1234567890abcdef12345678
refundExtraIdstringOptional

Memo / tag for the refund address, if required by the source network

Example: 1234567890
refstringOptional

Partner affiliate referral code (alias of refCode). Optional: without a code the swap is created as usual. Attributes the swap to the partner via their affiliate referral node.

Example: BSS67FAY
refCodestringOptional

Partner affiliate referral code. Attributes the swap to the partner via their affiliate referral node. Optional. If both ref and refCode are sent, ref wins. An unknown code is rejected with REFERRAL_CODE_NOT_FOUND.

Example: BSS67FAY
Responses
201

Order created (YiFi UUID + access token + deposit details)

application/json
fromTokenstringRequired

Source token ticker

Example: ETH
fromNetworkstringRequired

Source chain slug as sent in the request

Example: ETH
toTokenstringRequired

Target token ticker

Example: USDC
toNetworkstringRequired

Target chain slug as sent in the request

Example: ETH
providerstringRequired

Provider slug executing this swap

Example: providerX
transactionIdstringRequired

YiFi transaction ID. Use this to poll /v1/transactions/{id} for status updates.

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
accessTokenstringRequired

Issued once at swap creation. Store securely client-side (used for private flows and client-side transaction operations).

Example: a7f3c2d1e9b8405643543343252432aa
externalTransactionIdstringOptional

Provider-side transaction id when it differs from the YiFi UUID in transactionId.

Example: 1ad576f82276a5
statusstring · enumRequired

Initial swap status – always pending at the moment of creation

Example: pendingPossible values:
statusListobjectOptional

Granular step-by-step status map. All values are false at creation. Keys vary by provider and engine.

Example: {"pending":false,"confirming":false,"processing":false,"completed":false}
receiveAmountstringRequired

Expected output amount the recipient will receive

Example: 1850.25
expirationTimeobject · nullableOptional

Order expiration from provider response (JSON path configured as expirationTimePath on create-exchange endpoint)

Example: 2025-12-01T12:00:00.000Z
estimatedOutputstringOptional

Legacy: expected output amount (prefer receiveAmount)

Example: 1850.25
estimatedTimestringRequired

Expected time to complete the swap

Example: ~30s
depositAddressobject · nullableOptional

Address to send source funds to. Present for CEX and private routes. null for DEX routes where funds are pulled via smart contract.

Example: 0x1234567890abcdef1234567890abcdef12345678
extraIdTostringOptional

Memo / tag for the destination address, if required

Example: 1234567890
refundAddressstringOptional

Address that will receive funds if the swap fails

Example: 0x1234567890abcdef1234567890abcdef12345678
refundExtraIdstringOptional

Memo / tag for the refund address, if required

Example: 1234567890
txCreateMetaobject · nullableOptional

Raw transaction metadata returned by the provider at creation (e.g. hash, nonce). May be a JSON string.

Example: {"hash": "0x123...", "nonce": 42}
extraIdDepositstringOptional

Memo / tag for the deposit address, if required by the source network

Example: 1234567890
tokenForTxstringOptional

Ticker of the token as returned by the provider's internal createExchange response. May differ from fromToken in multi-hop DEX routes.

Example: USDT
post/v1/swap
POST /v1/swap HTTP/1.1
Host: api.yifi.io
x-api-key-partner: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 491

{
  "provider": "providerX",
  "fromToken": "ETH",
  "fromNetwork": "ETH",
  "toToken": "USDC",
  "toNetwork": "ETH",
  "engine": "cex",
  "amount": 1.5,
  "quoteId": "abc123",
  "rateId": "4f2e6d6b-6e15-4f47-8b6e-2a3d3c5b9d10",
  "receiveAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "addressFrom": "0x1234567890abcdef1234567890abcdef12345678",
  "slippageTolerance": "0.5",
  "extraIdTo": "1234567890",
  "refundAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "refundExtraId": "1234567890",
  "ref": "BSS67FAY",
  "refCode": "BSS67FAY"
}
{
  "fromToken": "ETH",
  "fromNetwork": "ETH",
  "toToken": "USDC",
  "toNetwork": "ETH",
  "provider": "providerX",
  "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "accessToken": "a7f3c2d1e9b8405643543343252432aa",
  "externalTransactionId": "1ad576f82276a5",
  "status": "pending",
  "statusList": {
    "pending": false,
    "confirming": false,
    "processing": false,
    "completed": false
  },
  "receiveAmount": "1850.25",
  "expirationTime": "2025-12-01T12:00:00.000Z",
  "estimatedOutput": "1850.25",
  "estimatedTime": "~30s",
  "depositAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "extraIdTo": "1234567890",
  "refundAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "refundExtraId": "1234567890",
  "txCreateMeta": "{\"hash\": \"0x123...\", \"nonce\": 42}",
  "extraIdDeposit": "1234567890",
  "tokenForTx": "USDT"
}
PreviousQuote
NextTransactions

Last updated

Was this helpful?