Skip to main content

​
Overview

The swap service supports the following scenarios:
  • Post-collection conversion: Convert received payments to settlement currency
  • Unified settlement currency: Maintain accounts in a single currency
  • Balance rebalancing: Optimize currency distribution across accounts
For request headers, signature rules, and callback verification, refer to Authentication & Security.

​
Integration Flow

The standard swap workflow follows these steps: 
Query tradable scope → Get quote → Create swap order → Query result
Each step is described in detail below.

​
Step 1: Query Tradable Currency Scope (Optional)

Endpoint: GET /v1/pay/convert/currency Retrieves the list of currencies available for conversion. This step is optional but recommended for user interface initialization and validation.

​
Query Parameters

ParameterTypeRequiredDescription
sidestringNoFilter by buy or sell direction

​
Response Fields

The response includes available currencies with precision and amount constraints:
  • minBuyAmount: Minimum buy amount (field precision rules apply)
  • maxBuyAmount: Maximum buy amount (field precision rules apply)
  • minSellAmount: Minimum sell amount (field precision rules apply)
  • maxSellAmount: Maximum sell amount (field precision rules apply)

​
Step 2: Query Available Currency Pairs (Optional)

Endpoint: GET /v1/pay/convert/pair Retrieves supported trading pairs and exchange rate information.

​
Query Parameters

ParameterTypeRequiredDescription
currencystringNoFilter pairs by base currency
sidestringNoFilter by buy or sell direction

​
Step 3: Get Quote

Endpoint: POST /v1/pay/convert/preview Generates a quote for currency conversion. The quote includes an expiration timestamp; expired quotes cannot be used for order creation.

​
Request Parameters

FieldTypeRequiredDescription
buyCurrencystringYesTarget currency to buy
sellCurrencystringYesSource currency to sell
buyAmountstringConditionalAmount to buy (mutually exclusive with sellAmount)
sellAmountstringConditionalAmount to sell (mutually exclusive with buyAmount)
Note: Provide either buyAmount or sellAmount, but not both.

​
Response Fields

FieldTypeDescription
quoteIdstringUnique quote identifier; required for order creation
exchangeRatestringCurrent exchange rate
buyAmountstringAmount in target currency
sellAmountstringAmount in source currency
expirationTimetimestampQuote expiration timestamp

​
Step 4: Create Swap Order

Endpoint: POST /v1/pay/convert Creates a currency conversion order using a valid quote. This endpoint is idempotent: submitting the same clientReqId multiple times will return the same business result.

​
Request Parameters

FieldTypeRequiredDescription
quoteIdstringYesQuote ID from Step 3
buyCurrencystringYesTarget currency
sellCurrencystringYesSource currency
buyAmountstringYesAmount to buy
sellAmountstringYesAmount to sell
clientReqIdstringYesMerchant-generated unique request ID for idempotency

​
Response Fields

FieldTypeDescription
orderIdstringPlatform order number for queries
clientReqIdstringEchoed from request
statusstringInitial order status (typically processing)
buyAmountstringFinal buy amount
sellAmountstringFinal sell amount

​
Example Request

{
  "quoteId": "QUOTE_abc123",
  "buyCurrency": "BTC",
  "sellCurrency": "USDT",
  "buyAmount": "0.5",
  "sellAmount": "21500",
  "clientReqId": "SWAP_20240101_001"
}

​
Step 5: Query Swap Order

Endpoint: GET /v1/pay/convert/order Queries the status and details of a swap order. Supports multiple query keys for flexibility.

​
Query Parameters

ParameterTypeRequiredDescription
orderIdstringConditionalPlatform order number
clientReqIdstringConditionalMerchant-generated request ID
Note: Provide either orderId or clientReqId (not both required, but at least one).

​
Response Fields

FieldTypeDescription
orderIdstringPlatform order number
clientReqIdstringMerchant request ID
statusstringOrder status (see enumeration below)
buyCurrencystringTarget currency
sellCurrencystringSource currency
buyAmountstringFinal buy amount
sellAmountstringFinal sell amount
completionTimetimestampOrder completion timestamp

​
Swap Order Status Enumeration

StatusDescription
processingOrder is being processed; check back later
successConversion completed successfully; funds are now in the account
failureConversion failed; funds returned to original account

​
Retry and Error Handling

​
Handling Uncertain Responses

If a network timeout or uncertain response occurs:
  1. Query first: Use GET /v1/pay/convert/order with clientReqId or orderId to determine final status
  2. Only retry if necessary: Only reuse the same clientReqId for order creation if the query result remains uncertain
  3. Preserve idempotency: Keep clientReqId unchanged to ensure the same business result

​
Common Failure Scenarios

Failure ReasonDescriptionResolution
Insufficient balanceAccount does not have enough funds in sell currencyFund the account or reduce sell amount
Unsupported trading pairCurrency pair is not availableUse a different currency pair
Expired quoteQuote lifetime has elapsedGenerate a new quote using POST /v1/pay/convert/preview
Invalid quantity precisionAmount does not match currency precision rulesAdjust amount to match precision requirements
Amount limit exceededAmount exceeds currency limitsReview limits via GET /v1/pay/convert/currency

​
Callback Behavior

The swap capability does not provide asynchronous callbacks. Final order confirmation must be obtained through the query API (GET /v1/pay/convert/order). For information on callbacks for other products, see Notification & Callbacks.

​
Institution API Integration

For institutional use cases, swap endpoints are available under the institution namespace:
CapabilityStandard EndpointInstitution Endpoint
Create swap orderPOST /v1/pay/convertPOST /transfer/open/institution/v1/pay/convert
Query swap orderGET /v1/pay/convert/orderGET /transfer/open/institution/v1/pay/convert/order
For complete institution API details, see Institution API.

​
Error Handling

For comprehensive error codes and resolution steps, refer to Error Codes & Best Practices.

​
Integration Checklist

  • Retrieve available currency pairs from GET /v1/pay/convert/pair
  • Implement quote retrieval with expiration handling
  • Generate unique clientReqId for each swap request
  • Create swap orders with valid quotes
  • Implement query fallback for order confirmation
  • Handle all failure scenarios gracefully
  • Store order IDs for reconciliation
  • Monitor conversion rates and limits