Swap Endpoints¶

This section covers API endpoints related to currency swaps. Swap operations allow users to exchange one currency for another within the platform using system-calculated rates. The main advantage of swaps is that they execute almost instantly at the current market rate, without waiting for specific price conditions to be met. Swaps are ideal for users who want to convert funds immediately at the current market price.

Get Available Swap Directions¶

Returns the list of swap directions available to the authenticated user.

GET /swap-directions

Required Permissions¶

• allow_swap

Rate Limit¶

30 requests per minute

Response Fields¶

List of swap direction objects.

Response Example¶

[
  {
    "code": "BTC-USDT",
    "spend_currency": "BTC",
    "receive_currency": "USDT",
    "spend_precision": 5,
    "receive_precision": 2,
    "min_spend_amount": "0.00050000",
    "max_spend_amount": null,
    "min_receive_amount": "10.00000000",
    "max_receive_amount": null,
    "is_enabled": true,
    "spend_rate_value": "1.00500000",
    "receive_rate_value": "20000.00000000",
    "fee_percent": "0.40000000"
  },
  {
    "code": "USDT-BTC",
    "spend_currency": "USDT",
    "receive_currency": "BTC",
    "spend_precision": 2,
    "receive_precision": 5,
    "min_spend_amount": "10.00000000",
    "max_spend_amount": null,
    "min_receive_amount": "0.00050000",
    "max_receive_amount": null,
    "is_enabled": true,
    "spend_rate_value": "20100.00000000",
    "receive_rate_value": "1.00000000",
    "fee_percent": "0.40000000"
  }
]

Response Fields¶

Create Swap¶

Initiates a swap between two currencies.

POST /swap/open

Required Permissions¶

• allow_swap

Rate Limit¶

300 requests per minute

Request Parameters¶

Example Request¶

{
  "direction": "BTC-USDT",
  "spend_amount": "0.01000000",
  "callback_url": "https://example.com/callbacks/swaps",
  "custom_id": "my-swap-123",
  "time_to_live": 30000
}

Response¶

{
  "code": "SWP123456",
  "custom_id": "my-swap-123",
  "callback_url": "https://example.com/callbacks/swaps",
  "direction": "BTC-USDT",
  "spend_currency": "BTC",
  "receive_currency": "USDT",
  "spend_amount": "0.01000000",
  "receive_amount": "294.85250000",
  "fee_amount": "0.73713125",
  "fee_currency": "USDT",
  "rate": "29485.25",
  "status": "open",
  "reason_code": null,
  "reason_message": null,
  "created_at": "2023-01-15T14:30:15Z",
  "updated_at": "2023-01-15T14:30:15Z",
  "done_at": null,
  "expires_at": "2023-01-15T14:30:45Z"
}

Response Fields¶

Cancel Swap¶

Cancels a pending swap.

POST /swap/cancel

Required Permissions¶

• allow_swap

Rate Limit¶

300 requests per minute

Request Parameters¶

At least one of the parameters code or custom_id must be provided. If both are provided, the code parameter will be used first.

Example Request¶

{
  "code": "SWP123456"
}

Response¶

Same as the swap object. Status may not be changed to cancelled instantly, as the system may need time to process the request. Instead cancel_requested_at will be set to the current time.

List Swaps¶

Returns a list of swaps.

GET /swap

Required Permissions¶

• allow_swap

Rate Limit¶

300 requests per minute

Query Parameters¶

Response¶

[
  {
    "code": "SWP123456",
    "custom_id": "my-swap-123",
    "callback_url": "https://example.com/callbacks/swaps",
    "direction": "BTC-USDT",
    "spend_currency": "BTC",
    "receive_currency": "USDT",
    "spend_rate": "1.0000000",
    "receive_rate": "29485.25000000",
    "spend_amount": "0.01000000",
    "receive_amount": "294.85250000",
    "amount_parameter": "spend",
    "fee_amount": "0.73713125",
    "fee_currency": "USDT",
    "spend_filled": "0.01000000",
    "receive_filled": "294.85250000",
    "spend_fee_filled": "0.00000000",
    "receive_fee_filled": "0.73713125",
    "status": "success",
    "reason_code": null,
    "reason_message": null,
    "created_at": "2023-01-15T14:30:15Z",
    "updated_at": "2023-01-15T14:35:20Z",
    "done_at": "2023-01-15T14:35:20Z",
    "valid_till": "2023-01-15T14:30:45Z",
    "cancel_requested_at": null
  }
  // More swaps...
]

Response Fields¶

Same as the create swap response. The results are returned as a direct array without pagination metadata.

Pagination¶

The API uses simple offset-based pagination with limit and offset parameters. Offset is limited for maximum 10000, if you set more - error will be returned. The default limit is 100, and the maximum limit is 200. The response is a direct list of swap objects without pagination metadata wrapper. If you need to fetch more than 200 swaps, you should use the start_at and end_at parameters to fetch swaps in smaller date ranges. List is sorted by creation date in descending order.

Get Swap Details¶

Returns details of a specific swap.

GET /swap/{code}

Required Permissions¶

• allow_swap

Rate Limit¶

300 requests per minute

Path Parameters¶

Response¶

Same as a single swap object from the list endpoint.

Swap Status Values¶

Callback Notifications¶

If a callback_url was provided when creating the swap, the system will send POST requests to this URL when the swap status changes.

Important Note: You may not receive callbacks for every intermediate status change or field update if changes occur very rapidly. When operations transition through multiple states quickly, intermediate callbacks may be skipped. However, you will always receive callbacks for the final states of operations. Design your callback handling to be idempotent and not dependent on receiving every single state transition.

Currently, callbacks are not signed. The signature mechanism for callbacks is planned for a future update. You should validate callback data by making an authenticated API request to verify the swap status.

Callback Payload¶

The callback payload contains the same data as the swap details response, with essential fields for status updates:

{
  "code": "SWP123456",
  "custom_id": "my-swap-123",
  "callback_url": "https://example.com/callbacks/swaps",
  "direction": "BTC-USDT",
  "spend_currency": "BTC",
  "receive_currency": "USDT",
  "spend_rate": "1.0000000",
  "receive_rate": "29485.25000000",
  "spend_amount": "0.01000000",
  "receive_amount": "294.85250000",
  "amount_parameter": "spend",
  "fee_amount": "0.73713125",
  "fee_currency": "USDT",
  "spend_filled": "0.01000000",
  "receive_filled": "294.85250000",
  "spend_fee_filled": "0.00000000",
  "receive_fee_filled": "0.73713125",
  "status": "success",
  "reason_code": null,
  "reason_message": null,
  "created_at": "2023-01-15T14:30:15Z",
  "updated_at": "2023-01-15T14:35:20Z",
  "done_at": "2023-01-15T14:35:20Z",
  "valid_till": "2023-01-15T14:30:45Z",
  "cancel_requested_at": null
}

Securing Callbacks¶

Since callbacks are not currently signed, you should implement these security measures:

1. Whitelist IPs: Accept callbacks only from the service's IP addresses. Contact support to get the list of server IPs.
2. Verify Data: Always make an authenticated API request to /swap/{code} to verify the status and details of any swap after receiving a callback.
3. Use HTTPS: Ensure your callback URL uses HTTPS to encrypt the data in transit.

Common Use Cases¶

• Currency conversion: Convert one currency to another
• Price discovery: Get current exchange rates
• Trade execution: Execute trades at current market rates