Crypto Exchanges

Overview

The Exchange module provides the infrastructure to carry out asset exchanges on behalf of customers —a particularly important feature for platforms that accommodate multiple asset types and currencies. This module includes a series of endpoints tailored to the needs of users looking to perform, monitor, and manage asset exchanges for their customers.

Offering functions from quoting to execution, along with detailed tracking mechanisms, the Exchange module endpoints include:

  1. Get Available Asset Pairs: Provides a full list of asset pairs enabled for the API user. The response will also include information on limits and minimums associated with each asset pair for exchanges.

  2. Get Quote for Exchange: Provides an estimate for an exchange, detailing the price and amount before the actual exchange is executed, ensuring that the customer is informed about the potential transaction.

  3. Sell Exchange: Enables a customer to sell an asset, converting it into another asset or currency as specified in the trade.

  4. Buy Exchange: Allows a customer to purchase an asset, facilitating the exchange through a defined asset pair and desired quantity.

  5. List Exchanges: Provides a generated list of asset exchanges, with the ability to filter by customer, order type, and more.

  6. Review Quote: If the price of the asset changes between the time of initiating the exchange, and when it is approved, this endpoint allows a customer to review a price change for an exchange following approval by the transaction compliance team.

  7. Confirm Sell Exchange: Once an updated price is retrieved from Review Quote, this endpoint will allow a customer to confirm the price change and initiate the exchange.

  8. Cancel Exchange: This endpoint will allow a customer to cancel an exchange that has been recently approved by transaction compliance, in scenarios where the price changes from when the exchange was initially requested.

Overall, the Exchange module is designed to offer a seamless and secure experience for handling the exchange requirements of customers, ensuring that users can manage these operations effectively with great precision and control.


Get Available Asset Pairs

Provides a full list of asset pairs enabled for the API user. The response will also include information on limits and minimums associated with each asset pair for exchanges.

  • Endpoint: /api/v1/customer/crypto-exchanges/availablepairs

  • Method: GET


Get Quote for Exchange

This endpoint provides a quoted market price for a proposed asset exchange for a particular customer, detailing the amount and price for either a "Buy" or "Sell" exchange type. By specifying details of the desired trade, a customer can see the cost or proceeds they might expect from completing a transaction, including any applicable fees. This helps customers decide whether to proceed with an exchange based on real-time financial data. Sell exchanges generally refer to converting a cryptocurrency into a fiat currency.

  • Endpoint: /api/v1/customer/crypto-exchanges/quote

  • Method: POST

Request Body Parameters:

  • customersId (Integer): ID of the customer making the exchange—required.

  • payeesId (Integer, Nullable): Id of receiving payee, if receiving account is a passthrough account.

  • assetPair (String): The pair of assets to be exchanged, such as "BTC/USDC"—required.

  • quantityType (String): Defines if the exchange is based on "Price" or "Amount"—required.

  • exchangeType (String): Either "Buy" or "Sell"—required.

  • transferType (String): The transfer type, such as "Wire"—required.

    • transferType is only required for sell exchanges where the “payeesId” is not null.

  • price (Decimal, Nullable): Desired price for a "Price"-based exchange, null for "Amount"-based.

  • amount (Decimal, Nullable): Desired amount for an "Amount"-based exchange, null for "Price"-based.

Request Example:

{
  "customersId": 1004,
  "assetPair": "BTC/USDC",
  "quantityType": "Price",
  "exchangeType": "Buy",
  "transferType": "Wire",
  "price": 10,
  "amount": null
}

Response Body Parameters:

  • id (Integer): Not used.

  • details (Object): Contains the quote details.

    • customersId (Integer): ID of the customer.

    • payeesId (Integer): The payee's ID to where the asset's sale proceeds will be credited. Required if receiving account is a passthrough account.

    • quantityType (String): Indicates whether "Amount" or "Price" is fixed for the exchange exchange.

    • assetPair (String): Asset pair involved in the exchange.

    • amount (Decimal): Amount of asset to be exchanged.

    • netPrice (Decimal): Exchange effective net price accounting for commission and network fees.

    • networkFee (Decimal): Estimated exchange network fee.

    • commissionFee (Decimal): The commission fee for the exchange.

    • price (Decimal): Total quoted price for the exchange.

    • fxRateId (Integer): FX rate ID that's to be used to for sell exchanges.

    • fxRateExpiryDate (ISO 8601): Expire date for given fxRateId. Once the current time is greater than the expire time, you must generate a new quote.

Success Response Example:

{
    "id": 0,
    "details": {
        "customersId": 1004, 
        "payeesId": null, 
        "quantityType": "Price", 
        "assetPair": "BTC/USDC", 
        "amount": 0.00037578, 
        "netPrice": 8.79938276, 
        "networkFee": 1.15086600, 
        "commissionFee": 0.04975124, 
        "price": 10.0,
        "fxRateId": 1234, 
        "fxRateExpiryDate": "2022-12-06T15:23:47.838+00:00"
    },
    "status": "1",
    "errors": []
}

Possible Error Codes

Error Message CodeDescription

Required

Named field missing or zero

Invalid

Value given for named field is invalid

Documents_Not_Verified

Cannot perform this action for this customer due to the KYC state

Amount_Must_Be_Positive

Invalid or missing amount


Sell Exchange

This endpoint is designed to initiate a sell exchange, allowing a customer to sell an asset at a given price or for a specific amount.

  • Endpoint: /api/v1/customer/crypto-exchanges/sell

  • Method: POST

Request Body Parameters:

  • customersId (Integer): The customer's ID who owns the asset to be sold—required.

  • assetPair (String): The pair of assets involved in the exchange, such as "BTC/USD"—required.

  • TransferType (String): The type of transfer to be used (e.g., "Wire")—required.

    • Possible Transfer Types

      Wire - FedWire, available to US accounts.

      ACH - Available to US accounts.

      RTP - Realtime Domestic US Payments, also known as FedNow. Available to US accounts.

      SWIFT - For international accounts.

      Internal - Internal Transfer to Ibanera Fiat acccount

  • fxRateId (String, Nullable): The FX rate ID to be used for the sell exchange, if applicable.

  • QuantityType (String): Specifies if the quote is for an "Amount" or "Price". Required if fxRateId is not provided.

  • amount (Decimal): The amount of asset to be sold, if QuantityType is "Amount". Amount or Price required if fxRateId is not provided - Required if quantityType is "Amount".

  • price (Decimal): The price at which the asset is to be sold, if QuantityType is "Price". Amount or Price required if fxRateId is not provided - Required if quantityType is "Price".

  • payeesId (Integer): The payee's ID to where the asset's sale proceeds will be credited. Required if receiving account is a passthrough account.

  • PurposeCode (String, Nullable): A code that signifies the reason for the transaction, for regulatory or record-keeping purposes. Required for FX sell orders. See the purpose code reference.

Request Body Example:

{
    "CustomersId": 1004,
    "PayeesId": 1011,
    "FxRateId": null,
    "AssetPair": "BTC/USD",
    "QuantityType": "Price",
    "TransferType": "Wire",
    "Price": 100,
    "Amount": 0.004,
    "PurposeCode": null
}

Response Body Parameters:

  • id (Integer): Not used.

  • details (Object):

    • id (Integer): A unique identifier for this sell exchange transaction.

    • exchangeType (String): Will show as "Sell" for most cases. .

    • status (String): The current status of the sell exchange (e.g., "Pending").

    • fromTransactionsId (Integer): Linked from transaction ID.

    • toTransactionsId (Integer, Nullable): Linked to transaction ID.

    • customersId (Integer): The customer's ID.

    • assetPair (String): The asset pair involved in the exchange.

    • requestAmount (Decimal): The amount requested to sell.

    • requestPrice (Decimal): The price requested for the sale.

    • executedAmount (Decimal, Nullable): The amount that was executed in the sale.

    • executedPrice (Decimal, Nullable): The price at which the sale was executed.

    • commissionFee (Decimal): The commission fee for the transaction.

    • payeesId (Integer): The ID of the payee's account where the proceeds will be credited.

    • transferType (String): The type of transfer from the asset account to the payee.

    • bHasOpenRfi (Boolean): Indicates whether there is an open request for information (relevant for FX only).

Success Response Example:

{
        "id": 0,
        "details": {
            "id": 23304,
            "exchangeType": "Sell",
            "status": "WaitingForApproval",
            "fromTransactionsId": 3410,
            "toTransactionsId": 3409,
            "customersId": 1004,
            "assetPair": "BTC/USDC",
            "requestAmount": 0.004,
            "requestPrice": 100.0,
            "executedAmount": 0.00415,
            "executedPrice": 100.0,
            "commissionFee": 1.50,
            "payeesId": 1011,
            "transferType": "Wire",
            "bHasOpenRfi": false
        },
        "status": "1",
        "errors": []
}

Possible Error Codes

Error Message CodeDescription

Required

Named field missing or zero

Invalid

Value given for named field is invalid

Documents_Not_Verified

Cannot perform this action for this customer due to the KYC state


Buy Exchange

This endpoint is intended for initiating a buy exchange, enabling a customer to purchase an asset at a specified price or quantity.

Using the Buy Asset feature, customers can securely order the purchase of digital assets such as Bitcoin using USDC, a stablecoin pegged to the US dollar. This order can be set at a specific price or amount, after which the system processes the order to buy at the most advantageous rates within set parameters, including applicable transaction fees.

  • Endpoint: /api/v1/customer/crypto-exchanges/buy

  • Method: POST

Request Body Parameters:

  • customersId (Integer): The ID of the customer initiating the purchase—required.

  • assetPair (String): The asset pair to be traded, such as "BTC/USDC"—required.

  • quantityType (String): Specifies the fixed value type in the quote, either "Price" or "Amount"—required.

  • amount (Decimal): The amount to be bought, used when the quantityType is "Amount"—required if quantityType is "Amount".

  • price (Decimal): The price at which to buy, used when the quantityType is "Price"—required if quantityType is "Price".

Request Example:

{
  "customersId": 1004,
  "assetPair": "BTC/USDC",
  "quantityType": "Price",
  "amount": 0.004,
  "price": 100
}

Response Body Parameters:

  • id (Integer): Not used.

  • details (Object):

    • id (Integer): The unique identifier for this buy exchange transaction.

    • exchangeType (String): Set to "Buy".

    • status (String): The status of the transaction, such as "Pending".

      • Possible values: WaitingForApproval, Rejected, WaitingForConfirmation, Pending, Completed, Failed

    • fromTransactionsId (Integer): The ID of the transaction debiting the payee.

    • toTransactionsId (Integer): The ID of the transaction crediting the customer.

    • customersId (Integer): The customer's ID.

    • assetPair (String): The asset pair for the exchange.

    • requestAmount (Decimal): The requested quantity to buy.

    • requestPrice (Decimal): The requested price for the buy.

    • executedAmount (Decimal): The actual quantity bought if the order is fulfilled.

    • executedPrice (Decimal): The price at which the order was executed.

    • commissionFee (Decimal): Fee charged for the transaction.

    • payeesId (Integer): Null for buy exchanges.

    • transferType (String): Null for buy exchanges.

    • bHasOpenRfi (Boolean): False for buy exchanges.

Success Response Example:

{
  "id": 0,
  "details": {
    "id": 23304,
    "exchangeType": "Buy",
    "status": "Pending",
    "fromTransactionsId": 3412,
    "toTransactionsId": 3411,
    "customersId": 1004,
    "assetPair": "BTC/USDC",
    "requestAmount": 0.004,
    "requestPrice": 100.0,
    "executedAmount": 0.00399,
    "executedPrice": 100.0,
    "commissionFee": 1.50
  },
  "status": "1",
  "errors": []
}

Possible Error Codes

Error Message CodeDescription

Required

Named field missing or zero

Invalid

Value given for named field is invalid

Documents_Not_Verified

Cannot perform this action for this customer due to the KYC state


List Exchanges

Provides a system generated list of crypto asset exchanges, with ability to filter by the type of exchange (Buy / Sell), the Status of the exchange, and CustomersID, asset pair.

  • Endpoint: /api/v1/customer/crypto-exchanges/buy

  • Method: GET

Request Query

Optional Request Query Parameters:

  • customersId (Integer): The ID of the customer initiating the purchase.

  • assetPair (String): The asset pair to be filtered, such as "BTC/USDC".

  • exchangeType (String): Specifies the type of exchanges to filter (possible values: Buy, Sell).

  • status (String): Exchange status filter

    • Possible values:

      WaitingForApproval - Awaiting review by transaction compliance team

      Rejected - Rejected by transaction compliance team

      WaitingForConfirmation - Requires Customer to approve / cancel new price

      Pending - Exchange Processing

      Completed - Exchange Completed

      Failed - Exchange Failed / Voided

  • PageNumber (Integer): List page number (default = 1)

  • PageSize (Integer): List page size (default = 10)

Request Query Example

{{endpoint}}/api/v1/customer/crypto-exchanges/list?CustomersId=1001

Response Body Example

{
    "id": 1001,
    "details": [
        {
            "id": 1001,
            "exchangeType": "Sell",
            "status": "WaitingForConfirmation",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "USDC/USD",
            "requestAmount": 4030.340000000000000000,
            "requestPrice": 4007.800000000000000000,
            "executedAmount": null,
            "executedPrice": null,
            "commissionFee": 20.140000000000000000,
            "payeesId": 1001,
            "transferType": "ACH",
            "bHasOpenRfi": false
        },
        {
            "id": 1002,
            "exchangeType": "Sell",
            "status": "Completed",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "USDC/USD",
            "requestAmount": 5037.320000000000000000,
            "requestPrice": 5009.640000000000000000,
            "executedAmount": 5037.320301634090314320,
            "executedPrice": 5009.640000000000000000,
            "commissionFee": 25.170000000000000000,
            "payeesId": 1001,
            "transferType": "ACH",
            "bHasOpenRfi": false
        },
        {
            "id": 1003,
            "exchangeType": "Buy",
            "status": "Pending",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "USDC/USD",
            "requestAmount": 48.430000000000000000,
            "requestPrice": 50.430000000000000000,
            "executedAmount": null,
            "executedPrice": null,
            "commissionFee": 0.000000000000000000,
            "payeesId": null,
            "transferType": null,
            "bHasOpenRfi": false
        },
        {
            "id": 1004,
            "exchangeType": "Sell",
            "status": "WaitingForConfirmation",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "USDC/USD",
            "requestAmount": 25.500000000000000000,
            "requestPrice": 20.000000000000000000,
            "executedAmount": null,
            "executedPrice": null,
            "commissionFee": 3.500000000000000000,
            "payeesId": 1001,
            "transferType": "ACH",
            "bHasOpenRfi": false
        },
        {
            "id": 1005,
            "exchangeType": "Sell",
            "status": "WaitingForConfirmation",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "USDC/USD",
            "requestAmount": 25.500000000000000000,
            "requestPrice": 20.000000000000000000,
            "executedAmount": null,
            "executedPrice": null,
            "commissionFee": 3.500000000000000000,
            "payeesId": 1001,
            "transferType": "ACH",
            "bHasOpenRfi": false
        },
        {
            "id": 1006,
            "exchangeType": "Sell",
            "status": "WaitingForConfirmation",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "USDC/USD",
            "requestAmount": 67.000000000000000000,
            "requestPrice": 39.990000000000000000,
            "executedAmount": null,
            "executedPrice": null,
            "commissionFee": 25.000000000000000000,
            "payeesId": 1001,
            "transferType": "Wire",
            "bHasOpenRfi": false
        },
        {
            "id": 1007,
            "exchangeType": "Sell",
            "status": "WaitingForConfirmation",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "ETH/USD",
            "requestAmount": 0.021422500000000000,
            "requestPrice": 40.510000000000000000,
            "executedAmount": null,
            "executedPrice": null,
            "commissionFee": 25.000000000000000000,
            "payeesId": 1001,
            "transferType": "Wire",
            "bHasOpenRfi": false
        },
        {
            "id": 1008,
            "exchangeType": "Sell",
            "status": "WaitingForConfirmation",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "ETH/USD",
            "requestAmount": 0.008122880000000000,
            "requestPrice": 20.030000000000000000,
            "executedAmount": null,
            "executedPrice": null,
            "commissionFee": 3.500000000000000000,
            "payeesId": 1001,
            "transferType": "ACH",
            "bHasOpenRfi": false
        },
        {
            "id": 1009,
            "exchangeType": "Buy",
            "status": "Completed",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "USDC/USD",
            "requestAmount": 16.748325170000000000,
            "requestPrice": 22.250000000000000000,
            "executedAmount": 16.740000000000000000,
            "executedPrice": 22.250000000000000000,
            "commissionFee": 3.500000000000000000,
            "payeesId": null,
            "transferType": null,
            "bHasOpenRfi": false
        },
        {
            "id": 1010,
            "exchangeType": "Sell",
            "status": "Completed",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "ETH/USD",
            "requestAmount": 0.013405240000000000,
            "requestPrice": 20.000000000000000000,
            "executedAmount": 0.013371975384448000,
            "executedPrice": 20.000000000000000000,
            "commissionFee": 25.000000000000000000,
            "payeesId": 1001,
            "transferType": "Wire",
            "bHasOpenRfi": false
        }
    ],
    "pageSize": 10,
    "pageNumber": 1,
    "numberOfPages": 2,
    "status": "1",
    "errors": []
}

Review Quote

When an exchange is flagged for compliance review, exchange rates may fluctuate between the time that a request was made, and when the request is approved. This endpoint will allow you to retrieve new prices for an exchange that was approved by our compliance team, for scenarios where the price of the asset has changed.

  • Endpoint: /api/v1/customer/crypto-exchanges/reviewquote

  • Method: POST

Example Request Body

{
    "ExchangesId": 5005
}

Response Parameters

  • CustomersId: Customer's Id

  • AssetPair: Asset pair to trade

  • QuantityType: Quantity type indicating whether price or amount is fixed (possible values: Price, Amount)

  • Amount: Amount to request to trade

  • NetPrice: Exchange effective net price accounting for commission and network fees

  • NetworkFee: Estimated exchange network fee

  • CommissionFee: Exchange commission fee

  • Price: Price to request to trade for

  • PayeesId: If receiving account is a passthrough account, receiving payee's Id (optional)

  • PreviousPrice: Previous exchange price before approval

  • PreviousAmount: Previous exchange amount before approval

Example Response Body

{
    "id": 5005,
    "details": {
        "previousPrice": 53.470000000000000000,
        "previousAmount": 58.983359712153660000,
        "customersId": 1000,
        "payeesId": 1001,
        "quantityType": "Amount",
        "assetPair": "USDC/USD",
        "amount": 58.983359712153660000,
        "netPrice": 58.970000000000000000,
        "networkFee": 2.00,
        "commissionFee": 0.710000000000000000,
        "price": 56.260000000000000000,
        "fxRateId": null,
        "fxRateExpiryDate": null
    },
    "status": "1",
    "errors": []
}

Confirm Sell Exchange

When an exchange is flagged for compliance review, exchange rates may fluctuate between the time that a request was made, and when the request is approved. This endpoint will allow you to confirm a price change and trigger the exchange to proceed.

The Amount and Price submitted in the body are from the response of Review Quote

  • Endpoint: /api/v1/customer/crypto-exchanges/confirmsell

  • Method: POST

Example Request Body

{
    "ExchangesId": 5005,
    "amount": 58.983359712153660000,
    "price": 56.260000000000000000
}

Example Response Body

{
    "id": 5005,
    "details": {
        "id": 5005,
        "exchangeType": "Sell",
        "status": "WaitingForApproval",
        "fromTransactionsId": 123455,
        "toTransactionsId": 123456,
        "customersId": 1000,
        "assetPair": "USDT/USD",
        "requestAmount": 58.983359712153660000,
        "requestPrice": 56.260000000000000000,
        "executedPrice": 53.470000000000000000,
        "commissionFee": 3.500000000000000000,
        "commissionFee": 0.710000000000000000,
        "payeesId": 1001,
        "transferType": "ACH",
        "bHasOpenRfi": false
    },
    "status": "1",
    "errors": []
}

Cancel Exchange

When an exchange is flagged for compliance review, exchange rates may fluctuate between the time that a request was made, and when the request is approved. This endpoint will allow you to cancel an exchange that was recently approved by our compliance team, when the price of an asset has changed.

  • Endpoint: /api/v1/customer/crypto-exchanges/cancel

  • Method: POST

Example Request Body

{
    "ExchangesId": 5005
}

Example Response Body

{
    "id": 0,
    "details": {
        "id": 5005,
        "exchangeType": "Sell",
        "status": "Failed",
        "fromTransactionsId": 123455,
        "toTransactionsId": 123456,
        "customersId": 1000,
        "assetPair": "USDC/USD",
        "requestAmount": 58.983359712153660000,
        "requestPrice": 53.470000000000000000,
        "executedAmount": 58.983359712153660000,
        "executedPrice": 53.470000000000000000,
        "commissionFee": 3.500000000000000000,
        "payeesId": 1001,
        "transferType": "ACH",
        "bHasOpenRfi": false
    },
    "status": "1",
    "errors": []
}

Last updated