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"
                }
            }
        }
    }
}
​
KYC
Next - API Integration
Settlements
Last updated 9 months ago
Intent To Trade

postIntent To Trade

Most Basic

Deal on Previously Quoted

Deal At Best

Include Settlement Method

Include Settlement Method and Parameters

post
Intent To Trade
