INinfini
Fund

Swap funds

Changed on

Exchanges between two different existing USDC, USDT, or USD WALLET accounts owned by the merchant associated with the API key. Requires fund.withdraw permission.

A USD Cash Account must already exist when either currency is USD. USDC/USDT swaps do not require a USD account. This endpoint does not open accounts.

Executes synchronously at the current applicable exchange rate and FX fee. No quote or rate reservation is required. amount includes the FX fee, charged in the source currency. A positive effective FX fee is rounded up to the smallest source currency unit (USD 0.01; USDC/USDT 0.000001). Explicit zero-rate merchant policies and exempt currency pairs still charge zero. The net amount is converted and truncated to target currency precision (USD: 2 decimals; USDC/USDT: 6).

min_output_amount is optional, non-negative, and denominated in the target currency. If the net rounded output falls below it, or rounds to zero, the swap is rejected without any debit or credit. Omitting it accepts the execution-time rate.

request_id is required and must be a UUID. Completed requests are persisted atomically with ledger changes. A retry by the same merchant returns the original output, price, and fee with is_duplicate=true, even after API key rotation. Changing either currency, amount, or minimum under the same ID is rejected. IDs are scoped to this operation and merchant. BW/RW identifiers are not supported. Failed attempts do not reserve a price or persist a completed result.

post/swap

Request

Headers

X-API-Key-IDstring required

32-character Base58 credential ID returned after public-key registration.

X-API-Timestampstring required

Unix timestamp in seconds; tolerance is ±300 seconds.

X-API-Noncestring required

16 cryptographically random bytes encoded as unpadded Base64URL; fresh on every attempt.

Digeststring required

SHA-256= followed by standard padded Base64 of SHA-256 of exact request body bytes. Required even for an empty body; included in the signing string.

Authorizationstring required

Use Ed25519 signature="BASE64_SIGNATURE", where BASE64_SIGNATURE is the standard padded Base64 signature. See /docs/en/4-authorization for the exact signing string.

Request body

request_idstring uuid required

Required UUID idempotency key; reuse on retry with unchanged parameters.

source_currency'USDC' | 'USDT' | 'USD' required

Source WALLET currency; must differ from target_currency.

target_currency'USDC' | 'USDT' | 'USD' required

Target WALLET currency.

amountstring required

Positive total source debit including FX fee. Plain decimal, no exponent; USD allows 2 decimals, USDC/USDT 6. Minor-unit value must fit a signed 64-bit integer.

min_output_amountstring

Optional non-negative minimum net target amount, using target currency precision and the same minor-unit range. Omission accepts the execution-time output. Zero disables the minimum but zero actual output is always rejected.

Example request

{
  "request_id": "e94b4e88-36c2-4550-907e-839742cf5fae",
  "source_currency": "USDC",
  "target_currency": "USD",
  "amount": "100",
  "min_output_amount": "99"
}

Response

Completed swap or a business error in the standard envelope

OR

Example response

{
  "data": {
    "request_id": "e94b4e88-36c2-4550-907e-839742cf5fae",
    "output_amount": "99.5",
    "price": "1",
    "fx_fee": "0.5",
    "fx_fee_currency": "USDC"
  }
}

Changes

  • b9ee797f5199Revision changes
    • breaking

      added the new required header request parameter X-API-Key-ID

    • breaking

      added the new required header request parameter X-API-Nonce

    • breaking

      added the new required header request parameter X-API-Timestamp

    • breaking

      the header request parameter Authorization became required

    • breaking

      the header request parameter Digest became required

    • breaking

      removed the media type application/json for the response with the status

    • breaking

      removed the media type application/json for the response with the status

    • warning

      deleted the header request parameter Date

  • b02cebfd84e4Revision changes
    • info

      endpoint added