Intent To Trade

The `/intent_to_trade` endpoint is a complex part of the API as it contains many optional fields allowing for partial completion of the transaction.

Update: This endpoint now requires a session_id to be provided.

post
Intent To Trade

​/api​/v1​/transaction​/intent_to_trade
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 and it the primary purpose of the endpoint. in the cases where more information is known at the time of calling, it is possible to supply that information and receive a more informative response. The extra fields include information regarding the quote, funding settlement, and payout settlement.
Request
Response
Request
Body Parameters
session_id
required
string
See User Session
client_ref
optional
string
Optional reference id created client side.
symbol
required
string
currency
required
string
side
required
string
quantity
required
string
quantity_2
optional
string
quote_id
optional
string
terms_of_service
required
object
allow_at_best_recovery
optional
boolean
funding_settlement
optional
object
payout_settlement
optional
object
Response
200: OK

Most Basic

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"
}
}

Deal on Previously Quoted

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"
}
}

Deal At Best

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"
}
}
}

Include Settlement Method

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
}
}
}
}

Include Settlement Method and Parameters

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"
}
}
}
}
}