Update: This endpoint now requires a session_id
to be provided.
The most basic request for intent_to_trade
is to simply supply one side of the transaction and the symbol. This returns a transaction_id
to correlate future calls.Request
Request
POST /api/v1/transaction/intent_to_trade{"api_key": "a57685a6-9d60-4d68-82f1-5e1fb5833ebb","symbol": "BCH/JPY","currency": "JPY","side": "buy","quantity": "350","terms_of_service": {"accepted": true,"terms_href": "https://help.liquid.com/en/articles/3969828-quick-exchange-by-liquid-end-user-terms-of-use"}}
Response [202]
{"success": true,"message": "Transaction record created. Settlement method required. Please specify settlement method via /settlement/method.","payload": {"client_ref": null,"transaction_id": "783f2d3a-68d2-4f00-9e58-b6fd5e19b7ef","api_key": "a57685a6-9d60-4d68-82f1-5e1fb5833ebb","status": "SETTLEMENT_METHOD_REQUIRED"}}
In most cases it is recommended to use the streaming quotes service to obtain a quote before submitting the intent_to_trade
request.
Request
POST /api/v1/transaction/intent_to_trade{"session_id": "e750928c-ef64-4206-9345-ac8d743feb1a","client_ref":"<unique_client_ref>","symbol": "BCH/BTC","currency": "BTC","side": "buy","quantity": "0.008","quantity_2": "0.21320","quote_id": "01DT8ZJWSQFWQKBW563EZDCZSF","terms_of_service": {"accepted": true,"terms_href": "https://help.liquid.com/en/articles/3969828-quick-exchange-by-liquid-end-user-terms-of-use"}}
Response [202]
In this response the transaction status is shown as SETTLEMENT_METHOD_REQUIRED
{"success": true,"message": "Transaction record created. Settlement method required. Please specify settlement method via /settlement/method.","payload": {"transaction_id": "2adb1cf4-e282-43d1-8d98-ce791746e8fe","api_key": "a57685a6-9d60-4d68-82f1-5e1fb5833ebb","status": "SETTLEMENT_METHOD_REQUIRED"}}
Dealing on a previous quote is recommended where possible. In cases where the end-user is not price sensitive, and it is not possible to fetch a quote separately, a snapshot quote can be obtained by submitting a intent_to_trade
request while specifying funding and payout methods and without reference to a quote.
Request
POST /api/v1/transaction/intent_to_trade{"session_id":"e750928c-ef64-4206-9345-ac8d743feb1a","client_ref":"<unique_client_ref>","symbol":"BTC/USD","currency":"USD","side":"buy","quantity":"100","terms_of_service": {"accepted": true,"terms_href": "https://help.liquid.com/en/articles/3969828-quick-exchange-by-liquid-end-user-terms-of-use"},"funding_settlement": {"method":"BLOCKCHAIN_TRANSFER"},"payout_settlement": {"method":"LIQUID_PARTNER_WALLET"}}
Response [202]
{"success": true,"message": "Transaction record created. All required input has been received.","payload": {"client_ref": "<unique_client_ref>","transaction_id": "f39aa8a5-0396-447a-aa53-ea337002a54e","status": "PENDING","funding_settlement": {"settlement_instruction_id": "160bde39-a652-4e6d-9a91-06a6fb6305c9","transaction_id": "f39aa8a5-0396-447a-aa53-ea337002a54e","currency": "BTC","direction": "FUNDING","method": "BLOCKCHAIN_TRANSFER","quantity": "0.01038","status": "PENDING","expires": {"unix_ms": 1583229915338,"iso8601": "2020-03-03T10:05:15.338Z","ttl_ms": 20000},"setup_parameters": {"account_key": {"type": "WALLET_ADDRESS","label": "Wallet Address","value": "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy"}}},"payout_settlement": {"settlement_instruction_id": "72c9927a-6fb7-437d-906a-34fdbbb05c59","transaction_id": "f39aa8a5-0396-447a-aa53-ea337002a54e","currency": "USD","direction": "PAYOUT","method": "LIQUID_PARTNER_WALLET","quantity": "100.0","status": "PENDING"}}}
Funding and payout methods must be specified to obtain settlement instructions for for each leg of the transaction. In some cases it may be desirable to allow the user to select which methods after creating the transaction_id
, and a separate endpoint exists to allow for that. In most cases funding and payout methods are known at time of intent_to_trade
and can be supplied immediately.
Request
POST /api/v1/transaction/intent_to_trade{"session_id": "e750928c-ef64-4206-9345-ac8d743feb1a","client_ref": "<unique_client_ref>","symbol": "BCH/JPY","currency": "JPY","side": "buy","quantity": "350","quantity_2": "0.014650","quote_id": "01DT8ZJWSQFWQKBW563EZDCZSF","terms_of_service": {"accepted": true,"terms_href": "https://help.liquid.com/en/articles/3969828-quick-exchange-by-liquid-end-user-terms-of-use"},"allow_at_best_recovery": true,"funding_settlement": {"method": "BLOCKCHAIN_DELEGATED_BROADCAST"},"payout_settlement": {"method": "LIQUID_PARTNER_WALLET"}}
Response [202]
In this response the transaction status is shown as SETTLEMENT_PARAMETERS_REQUIRED
indicating that the transaction is waiting on parameters to be supplied.
For example, specifying BLOCKCHAIN_DELEGATED_BROADCAST
as the funding method requires supplying a value for mandatory parameter SIGNED_RAW_TRANSACTION
.
{"success": true,"message": "Transaction record created. Parameters required. Please check `required_input` field on any settlement instructions.","payload": {"client_ref": null,"transaction_id": "e71e19a6-6976-4fc3-afe9-b6b227e1ae1e","session_id": "e750928c-ef64-4206-9345-ac8d743feb1a","status": "SETTLEMENT_PARAMETERS_REQUIRED","funding_settlement": {"settlement_instruction_id": "75decaee-522a-4731-9a54-367c365d1c3d","transaction_id": "e71e19a6-6976-4fc3-afe9-b6b227e1ae1e","currency": "BCH","direction": "FUNDING","method": "BLOCKCHAIN_DELEGATED_BROADCAST","quantity": "0.014650","status": "PARAMETERS_REQUIRED","expires": {"unix_ms": 1585815616765,"iso8601": "2020-04-02T08:20:16.765Z","ttl_ms": 20000},"setup_parameters": {"account_key": {"type": "WALLET_ADDRESS","label": "Wallet Address","value": "35LRi6UN5XtJBYaunQWQ9pUo9Pcf3QLtY3"}},"required_input_parameters": {"transaction_key": {"type": "SIGNED_RAW_TRANSACTION","required": true}}},"payout_settlement": {"settlement_instruction_id": "5e2a7b2a-e5a7-4ce3-9555-fa502af52548","transaction_id": "e71e19a6-6976-4fc3-afe9-b6b227e1ae1e","currency": "JPY","direction": "PAYOUT","method": "LIQUID_PARTNER_WALLET","quantity": "350","status": "NOT_STARTED","expires": {"unix_ms": 1585815617859,"iso8601": "2020-04-02T08:20:17.859Z","ttl_ms": 20000}}}}
In situations where required parameters and their values are known ahead of time, such as knowing wallet address is mandatory for blockchain payouts, it is possible to minimize the API interactions by submitting values within the intent_to_trade
request.
Request
POST /api/v1/transaction/intent_to_trade{"session_id": "e750928c-ef64-4206-9345-ac8d743feb1a","symbol": "BTC/BCH","currency": "BCH","side": "sell","quantity": "0.03","quantity_2": "0.0010040","quote_id": "01E4WYZCKN3ZFJTCFTA8X687YZ","terms_of_service": {"accepted": true,"terms_href": "https://help.liquid.com/en/articles/3969828-quick-exchange-by-liquid-end-user-terms-of-use"},"allow_at_best_recovery": true,"funding_settlement": {"method": "BLOCKCHAIN_TRANSFER"},"payout_settlement": {"method": "BLOCKCHAIN_TRANSFER","input_parameters": {"account_key": {"type": "WALLET_ADDRESS","value": "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy"}}}}
Response [202]
{"success": true,"message": "Transaction record created. Parameters required. Please check `required_input` field on any settlement instructions.","payload": {"client_ref": null,"transaction_id": "a771ae79-5dfc-4c11-ba56-3c67f95d1116","session_id": "e750928c-ef64-4206-9345-ac8d743feb1a","status": "SETTLEMENT_PARAMETERS_REQUIRED","funding_settlement": {"settlement_instruction_id": "5518b873-1ade-4954-811d-eefb86aa5661","transaction_id": "a771ae79-5dfc-4c11-ba56-3c67f95d1116","currency": "BCH","direction": "FUNDING","method": "BLOCKCHAIN_TRANSFER","quantity": "0.03","status": "WAITING_USER","expires": {"unix_ms": 1585815701970,"iso8601": "2020-04-02T08:21:41.970Z","ttl_ms": 20000},"setup_parameters": {"account_key": {"type": "WALLET_ADDRESS","label": "Wallet Address","value": "35LRi6UN5XtJBYaunQWQ9pUo9Pcf3QLtY3"}}},"payout_settlement": {"settlement_instruction_id": "4aebc1a0-fa7f-41f6-b9b3-be1f139deac9","transaction_id": "a771ae79-5dfc-4c11-ba56-3c67f95d1116","currency": "BTC","direction": "PAYOUT","method": "BLOCKCHAIN_TRANSFER","quantity": "0.0010040","status": "PARAMETERS_REQUIRED","expires": {"unix_ms": 1585815703637,"iso8601": "2020-04-02T08:21:43.637Z","ttl_ms": 20000},"received_input": {"account_key": {"type": "WALLET_ADDRESS","value": "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy"}}}}}