Operate on Tradelink As A Liquidity Provider (Exchange)
- XC create Settlement request
- XC approves creation Settlement request
-
XC approves Pledge request
Settlement
Settlement instructions will be provided by an Exchange or Settlement platform (Vault role name: Exchange) at the end of the trading period (EoD, intraday, ad hoc) as agreed among the Settlement creator (Vault role name: Exchange), collateral agent (Vault role name: Custodian), and the trading institution (Vault role name: Asset Manager).
The settlement instructions will be provided by the Exchange/Settlement platform as an API request to be reviewed and approved by the collateral agent (Vault role name: Custodian).
An optional pre-approval has been introduced to allow a trading institution (Vault role name: Asset Manager) to show its intention to proceed with the settlement request and to signal to the collateral agent (Vault role name: Custodian) that it has reviewed the requests and it is comfortable to proceed.
In upcoming releases, we will introduce Account edition which will give the possibility to add additional approvers (e.g. independent third parties to verify settlement instructions) to the approval flow.
EXCHANGE SETTLEMENT REQUEST CREATION
As an API operator (Exchange) authorized to send settlement requests on a Tradelink account, to create settlement requests the Exchange will need to:
-
Set up an environment on Postman or similar client-side applications and add the following environment variables:
a. API Key ID
b. Secret generated during the API operator registration process
C. URL of your Ledger Enterprise (Vault) instance
- Authenticate as an Exchange using the steps described here . This will provide the JWT authorization bearer token (access_token) to authenticate.
GET request
End point:{{URL}}/auth/token
Body:
{"api_key_id":"{{api_key_id}}","api_key_secret": "{{api_key_secret}}"- The API operator Exchange will then get the list of pledges that are available to be settled
GET {{api_url}}/pledges
Content-Type: application/json
X-Ledger-Workspace: {{workspace}}
Authorization: Bearer {{jwt_token}}
curl --request GET \
--url https://api.vault.ledger.com/pledges \
--header 'authorization: Bearer {{access_token}}' \
--header 'content-type: application/json' \
--header 'x-ledger-workspace: workspace'Example: Search Pledge
NOTE: In order to proceed with the settlement request the original pledge request raised by the API operator Asset Manager needs to be in “ready” state not “pending approval”. Further below in the section EXCHANGE PLEDGE REQUEST APPROVAL will describe how to approve a pledge request.
{
"edges": [
{
"cursor": 0,
"node": {
"account": {
...
},
"amount": 0,
"asset_manager": {
"approver_group_id": 5,
"code": "AM",
"id": 1,
"name": "Oneof",
"role": "ASSET_MANAGER",
"whitelist_id": 3
},
"custodian": {
"approver_group_id": 1,
"code": "KOM",
"id": 2,
"name": "Komainu",
"role": "CUSTODIAN",
"whitelist_id": 5
},
"exchange": {
"approver_group_id": 3,
"code": "CCc",
"id": 3,
"name": "Crypto.com",
"requires_pre_approval": false,
"role": "EXCHANGE",
"whitelist_id": 4
},
"id": "3ef749f1-983d-47fd-b95a-77ff442cef73",
"pending": 0,
"pledge_subaccount_id": 1,
"state": "PLEDGE_READY"
}
}
],
"page_info": {
"count": 3,
"has_next_page": false
}
}- The API operator Exchange will then be ready to raise a request for settlement creation which includes inbound and outbound transaction requests:
Inbound for the amount that the Asset Manager is expected to receive from the Exchange.
Outbound for the amount that the Exchange is expected to receive from the Asset Manager.
Inbound:
{
"amount": "{{amount}}",
"to_address": "{{address}}",
"to_account_id": {{to_account_id}}
}Outbound:
{
"from_pledge_id": "{{pledge_id}}",
"data": {
<transaction_data>
}
}amount = the amount that it is expected to be settled.
address = the address to which the amount should be transferred to.
to_account_id = the account id on the Vault associated to this address.
pledge_id = the unique identifier UUID of the pledge from which the settlement will be withdrawn.
transaction_data = request payload of the transaction data that will be sent to Ledger Enterprise (Vault). This is use also for standard transaction creation, instructions on how to create the payload can be found here.
{
"type": "CREATE_TRANSACTION",
"data": {
"account_id": 2,
"transaction_type": "BITCOIN_LIKE_SEND",
"transaction_data": {
"currency": "bitcoin_testnet",
"account_name": "ClientA COL TBTC 1",
"max_fees": "{{max_fees??}}",
"recipient": "tb1q5tsjcyz7xmet07yxtumakt739y53hcttmntajq",
"amount": "200000000"
},
"fees_strategy": {
"type": "SPEED",
"data": {
"speed": "FAST"
}
}
}
}NOTE: The outbound amount should always be equal to or less than the pledge amount, and the pledge_id is how the reference between the settlement request and the pledge is maintained.
NOTE: In the outbound transaction definition, we reuse the same format as for creating a transaction with POST /requests and request type CREATE_TRANSACTION.
The transaction request creation payload used for a given outbound transaction definition depends on the currency, it also means that specific rules still apply here, including the use of max_fees.
The endpoint to estimate transaction fees will be useful to compute the max_fees value from the transaction_data you expect to use in the outbound transaction part of the settlement creation payload.
NOTE: use the estimate max_fees endpoint to correctly set maxfees on each settlement transaction request. This will avoid that the request to be interrupted by the HSM during maxfees verification because too low or because not present.
curl --request POST \
--url https://api.vault.ledger.com/transactions/estimate-fees \
--header 'authorization: Bearer {{access_token}}' \
--header 'content-type: application/json' \
--header 'x-ledger-workspace: workspace' \
--data '{
"type": "CREATE_TRANSACTION",
"data": {
"account_id": 2,
"transaction_type": "BITCOIN_LIKE_SEND",
"transaction_data": {
"currency": "bitcoin_testnet",
"account_name": "ClientA COL TBTC 1",
"max_fees": "{{max_fees??}}",
"recipient": "tb1q5tsjcyz7xmet07yxtumakt739y53hcttmntajq",
"amount": "200000000"
},
"fees_strategy": {
"type": "SPEED",
"data": {
"speed": "FAST"
}
}
}
}'EXCHANGE SETTLEMENT REQUEST CREATION APPROVAL
The settlement creation request will create a transaction creation request for each of the outbound transactions (none if there is no outbound transaction). If there is no outbound transaction no approval is required.
Once posted the Vault will return the following responses:
{
"id": "36a45ef2-0e08-4ff5-bef5-6569c1851251",
"inbound_transaction_intents": [
{
"amount": 12000,
"to_account_id": 2,
"to_address": "tb1qhx0mksx6ce79yjsd2an4hxmw98kwxl8munzhzr"
}
],
"meta": {},
"outbound_transactions": [
{
"pledge_id": "3ef749f1-983d-47fd-b95a-77ff442cef73",
"transaction_hash": null,
"transaction_id": 132,
"request_id": 1234,
}
],
"state": "PRE_APPROVED"
}Those requests will need to be authorized by the API operator Exchange in order to be submitted for final approvals to the API operators Asset Manager, and Custodian.
Approval can be given using the standard approval method described here passing the {request_id} as request id.
EXCHANGE PLEDGE REQUEST APPROVAL
As described before API operator Exchange is responsible for approving every Pledge request raised by an API operator Asset Manager, this is so there is no ambiguity on whether the pledge request has been received and acknowledged.
For the API operator Exchange to approve the request the standard approval request method described here will be used by passing request_id.