Liquidity API Integration Guide

Overview

Prime Trust Liquidity is an API-based solution that enables integrators to offer crypto-to-fiat trading pairs. Sourcing from a pool of liquidity across a number of leading exchanges and market makers, Liquidity trades on a riskless principal basis, providing liquidity to clients directly on a non-disclosed basis.

Key terms

Asset A digital asset, such as Bitcoin or Ethereum.

Facilitated trade An executed Quote.

Trade desk A third-party API provider that accepts requests for quote (RFQ) and Quote execution.

Quote Price returned by a trade desk after a request is made to trade assets for cash or vice-versa.

Quote execution The process of both parties (trade desk and integrator) agreeing to execute a trade at a quoted price/amount.

Settlement Internal movement of cash/assets to and from accounts in the Prime Trust Core Platform to settle executed trades. Available assets

The following assets are available for trading in USD pairs:

  • BTC

  • LTC

  • ETH

  • USDT

  • USDC

How it works

  1. An integrator requests a quote using POST /v2/quotes. The trade desk id can be specified in the request if the integrator wants to route the quote to a specific trade desk.

  2. The request is sent to either a default, backup (if the default returns an error) or specified trade desk (if a trade desk id is included in the request). Upon success, the trade desk returns a quote that is valid for a specified duration.

  3. The integrator accepts or rejects the quote.

  4. Upon acceptance, the integrator executes the quote using POST /v2/quotes/{quote-id}/execute, which upon success results in an atomic bilateral settlement.

    a. The system records a facilitated trade for the executed quote.

Features

Request for Quote

Specify a sale or purchase using either unit count or amount. Alternatively, you can specify a trade desk ID to route your quote request to a specific trade desk rather than requesting a quote through the default routing system.

Smart routing

When you request a quote without specifying a trade desk, it is routed to a trade desk that can support it. Smart routing includes both a default and backup trade desk. If the default trade desk fails, the quote is automatically routed to the default.

Instant or delayed settlement

Instant settlement requires funds be available in Prime Trust Custody accounts at the time of quote execution. Delayed settlement gives both sides of each trade enough time to contribute cash/assets into our system before settlement occurs.

Automated reconciliation

Prime Trust monitors for discrepancies in status trades in our system and trades in our trade desks’ systems. If a discrepancy is found, the trade is flagged and either automated/manual action is taken to resolve the discrepancy.

Integrator prerequisites

  • Prime Trust Custodial Account

  • Configuration setup for Delayed Settlements (configured by Prime Trust)

    • This is only necessary if integrator will be using delayed settlement

    • Delayed settlement must be configured per trade desk with an agreement from the trade desk with the integrator

API Integration

Quotes

The quotes resource captures the entire lifecycle of a trade, from quote request to trade execution.

Request a quote

Use POST /v2/quotes/ to request a quote from the Prime Trust trade desk liquidity network.

Example:

{
"data":
{
"type": "quotes",
"attributes":
{
"account-id": ”id-xxxx-xxxx-xxxx”,
"asset-id": "id-xxxx-xxxx-xxxx",
"transaction-type": "buy",
"amount": "100.00"
}
}
}

The account-id attribute specifies the account that will be used to settle the trade resulting from quote execution. For example, you would specify an account holding USD for a BTC buy request.

You can specify the unit count (unit-count) of the digital asset you want to buy/sell or the amount (amount) in USD that you want to use in order to buy/sell the digital asset.

You can optionally specify a trade-desk-id attribute if you need to override the Prime Trust default providers. If you are using delayed settlement, specify a trade-desk-id, “skip_retry”: true, and “delayed_settlement”: true.

The expires-at response attribute returns the window for quote requests before the quote expires. The expiration time window will be 10 seconds for all quotes. However, actual execution window times can be as short as eight seconds (including the time for processing requests, which takes about three seconds).

Execute a quote

Use POST /v2/quotes/{quote-id}/execute/ to execute a Quote.

For instant settlement trading, you'll need to have enough existing funds in the specified account-id in order to successfully settle the executed quote. Once executed, the system initiates internal transfers to settle the trade and creates corresponding ledger entries. In the case of an execution failure, an error will be surfaced in the execution response and no internal transfers will be initiated.

Use GET /v2/quotes/ to return a list of your quotes.

Use GET /v2/quotes/id/ to return a specific quote.

Delayed settlements

A trade settlement object represents one instance of settlement between a trade desk and an integrator and can be created manually or automatically.

Feature Flags

To enable Delayed Settlement, speak to your Prime Trust Account Manager to ensure that your organization-level “delayed settlement” feature flags are enabled.

Prime Trust will also configure the following policies based on your integration requirements:

Settlement delay - X number of minutes from settlement resource creation until the first settlement will be attempted for that resource.

Settlement account - In case an end user does not have enough funds in their custodial account for settlement, you can specify an account that will be used to settle the trade. The integrator will then hold the settled cash/assets until the end user makes a successful contribution. If null, the system will not be able to settle trades between the trade desk liquidity account and end user accounts with a lack of cash/assets.

Auto settlement days - This policy determines how long after execution trades will be automatically linked to a settlement resource. For example, if you want to settle a quote in T+3 days, set a value of 3. This policy provides a time window in which to call the Liquidity Settlement endpoint to manually settle trades before the automated settlement process begins.

Auto settlement time - This policy defines at what time each day trades will be automatically linked to a settlement resource if they haven’t been manually linked to a settlement resource after the time specified in the “auto settlement” policy.

Settlement delay minutes - X number of minutes since initial settlement creation.

Settlement retry delay minutes - X number of minutes between each automated settlement retry.

Rejection delay minutes - After X number of minutes since settlement resource creation, the settlement resource and all linked quotes transition to “rejected” (end state).

Automated trade settlement

Once a day at a time specified in the account policy, a scheduled job will automatically aggregate all executed_pending_settlement quotes not already linked to a trade settlement object and link them to a newly created trade settlement object based on your auto_settlement account policy.

Create new flow:

  1. On time T, X number of trades are executed with “delayed settlement”: true with an auto_settlement_days policy of 3.

  2. On time T+3, a trade settlement object is created.

  3. Quotes are automatically linked to a trade settlement object.

  4. The trade desk’s exposure is calculated and stored in the trade settlement object.

  5. A webhook payload is sent to the trade desk and integrator with trade settlement object details.

Delayed settlement flow

After the settlement_delay_minutes time has elapsed after initial trade settlement creation or the retry_settlement_delay_minutes time has elapsed after the previous settlement attempt, the system will attempt to settle all executed_pending_settlement quotes linked to pending settlement resources or settlement_failed settlement resources.

  1. One-by-one, check balances for each trade.

    a. Check the following accounts to see if there are enough cash/assets for settlement:

    • Initiator: end user accounts and/or settlement account

    • Trade desk: liquidity account

    b. Place holds on cash/assets required for settlement.

  2. One-by-one, settle each trade.

  • Release hold on cash/assets required to settle trade.

  • Create internal transfers to settle trade.

  1. Transition status of quote object is set to settled and flagged as "integrator_settled”: true if necessary.

  2. Once all trades have been settled, transition the status of the Trade Settlement object to settled.

  3. Send webhook notifications to the trade desk and the integrator with settlement details.

Webhook notifications for settlement

Depending on where the trade settlement is in its life cycle, the system sends different webhook notifications to the the integrator and trade desk.

The following is sent in each webhook:

  • The event status (‘create’, ‘settle’, ‘failed’, ‘reject’)

  • Time at which the event occurred (‘created_at’, ‘settled_at’, ‘rejected_at’, ‘failed_at’)

  • Trade Settlement details (attributes: ‘asset_exposures’, ‘cash_exposures’, ‘automatically_created’, ‘organization_id’, ‘trade_desk_id’, ‘trade_settlement_pair_id’, ‘broker_account_id’)

Trade Settlement created

The trade settlement is created and exposure has been calculated for the trade desk.

The trade desk and integrator is notified with trade settlement details.

Settlement failed - maps to Delayed Settlement flow step 1

The trade desk’s liquidity account and/or integrator’s settlement account and end user accounts did not have enough cash/assets for settlement. The integrator and trade desk are notified with:

  • Trade Settlement details

  • If settlement account does not have enough cash/assets:

    • current cash/asset balances in instant settlement account

    • amount of cash/assets needed in instant settlement account for settlement

Settlement partial success - maps to Delayed Settlement flow step 5

The settlement was successful but one or more end user accounts did not have enough cash/assets for settlement. One or more quotes had to be settled between the liquidity account and the settlement account.

Settlement successful - maps to Delayed Settlement flow step 5

The trade desk’s liquidity account and all end user accounts had enough cash/assets for the settlement. The integrator and trade desk are notified with trade settlement details.

Settlement rejected

All automated and manual attempts to settle trades linked to the trade settlement have failed and the rejection_delay_minutes time has elapsed. The trade settlement resource and all linked quotes transition to “rejected.” The integrator and trade desk are notified with trade settlement details.

Manually create a trade settlement

Use POST /v2/trade-settlement-pairs/:id/trade-settlements. The request requires settlement attributes and the facilitated trade id. When called with an array of “executed_pending_settlement” trades not already linked to a trade settlement object, allows you to create a new trade settlement object.

The endpoint accepts an array of ids for quotes with the following traits:

  • all quotes must be in the “executed_pending_settlement” state

  • all quotes must have same trade_desk_id

  • not linked to a trade settlement object

Creation flow:

  1. Call to POST /v2/trade-settlement-pairs/:id/trade-settlements.

  2. A trade settlement object is created.

  3. Quote resources are linked to the newly created trade settlement object.

  4. The trade desk exposure is calculated for the trade settlement object.

Manually execute a trade settlement

Use POST /v2/trade-settlements/{trade-settlement-id}/settle. The request requires a trade settlement with a status in “pending” or “settlement_failed”. When called successfully, the endpoint triggers a settlement attempt for the trade settlement object.

Retrieve all trade settlements

Use GET /v2/trade-settlements. Returns an array of all an organization’s settlement resources or settlement resources based on the filter.

Retrieve an individual trade settlement

Use GET /v2/trade-settlements/{trade-settlement-id}. Retrieves a single settlement resource for the organization.

Sandbox testing

You can use the mock trade desk that supports all trading pairs and has an infinite supply of fiat and assets.

Errors

Quotes

  • 422: input validation errors (for example, amount too low, unit count too precise, not enough funds in the initiator account)

  • 400: Trade desk failure

Trade settlements

  • 422

    • when “No facilitated trades found”

    • when the quote status is not, “must be executed_pending_settlement”

    • when the quote does not share the same trade desk: “must be same trade desk”

    • when “Rolling Limit Reached”

    • when “Trade Settlement Pair Not Found”

Appendix A: Data models

Quote data model

The object used to represent quote requests.

AttributeData TypeDescription
trade-idstringId of associated facilitated_trade resource.
base-amountfloatAmount not including fees.
fee-amountfloatFee amount in USD.
total-amountfloatTotal amount of USD that the digital asset is being bought/sold for. This amount includes fees.
price-per-unitfloatQuoted price for one unit of the digital asset.
unit-countfloatCount of digital assets that are being bought/sold. If the unit count is specified in the request for POST /v2/quotes, a quote will be returned from the trade desk with an amount.
asset-namestringName of digital asset that is being traded (ex. “BTC”).
statusstringStatus of quote. Can be: "pending" - quote request was sent; "cancelled" - quote request was cancelled; "expired" - quote request is expired; "executing" - quote request is executing; "executed_pending_settlement" - executing quote is pending; "executed (settled)" - executed quote is settled
hotbooleanDefault is "true". If false, the quote will be settled out of the trade desk’s cold balance.
reconciliation-statusstringInternal trade reconciliation status.
'created-at'timestampTime when quote is created.
cancelled-attimestampTime when quote is cancelled.
expires-attimestampTime when quote will expire.
`executed-at'timestampTime when Quote was executed.
delayed-settlementbooleanCan only be specified in request if API user’s organization-level “delayed_settlement” account policy is enabled.

Trade settlement data model

AttributeData TypeDescription
settled-attimestampThe time at which a trade was settled.
failed-attimestampThe time at which settlement attempt failed.
rejected-attimestampThe time at which a trade was rejected.
integrator-settledbooleanIf true, indicates that the end user account did not have enough funds to cover a trade, and that the integrator’s settlement account was used instead.
statusstringStatus representing where the trade settlement is in its life cycle: "pending"; "settlement_failed"; "settled"; "rejected"
asset-exposurehashWhen buying, the trade desk will need to know the total unit_count needed to settle all linked trades (both exposures are calculated by aggregating all linked trades).
cash-exposureintegerWhen selling, the trade desk will need to know the total amount needed to settle all linked trades.
Last updated on