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:
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.
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.
Sell Exchange: Enables a customer to sell an asset, converting it into another asset or currency as specified in the trade.
Buy Exchange: Allows a customer to purchase an asset, facilitating the exchange through a defined asset pair and desired quantity.
List Exchanges: Provides a generated list of asset exchanges, with the ability to filter by customer, order type, and more.
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.
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.
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:
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 givenfxRateId
. Once the current time is greater than the expire time, you must generate a new quote.
Success Response Example:
Possible Error Codes
Error Message Code | Description |
---|---|
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
orPrice
required if fxRateId is not provided - Required ifquantityType
is "Amount".price
(Decimal): The price at which the asset is to be sold, if QuantityType is "Price".Amount
orPrice
required if fxRateId is not provided - Required ifquantityType
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:
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:
Possible Error Codes
Error Message Code | Description |
---|---|
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 thequantityType
is "Amount"—required ifquantityType
is "Amount".price
(Decimal): The price at which to buy, used when thequantityType
is "Price"—required ifquantityType
is "Price".
Request Example:
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:
Possible Error Codes
Error Message Code | Description |
---|---|
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 filterPossible values:
WaitingForApproval
- Awaiting review by transaction compliance teamRejected
- Rejected by transaction compliance teamWaitingForConfirmation
- Requires Customer to approve / cancel new pricePending
- Exchange ProcessingCompleted
- Exchange CompletedFailed
- Exchange Failed / Voided
PageNumber
(Integer): List page number (default = 1)PageSize
(Integer): List page size (default = 10)
Request Query Example
Response Body Example
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
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
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
Example Response Body
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, when the price of an asset has changed.
Endpoint:
/api/v1/customer/crypto-exchanges/cancel
Method:
POST
Example Request Body
Example Response Body
Last updated