# Request for Quote (RFQ)

<mark style="color:blue;">**`POST`**</mark> `https://api.sfox.com/v1/quote`

Returns an actionable one-sided quote for the specified currency pair.

After sending an RFQ, the API will return a quote with a price at which a trade can be executed. If you agree with the price, you can request the execution of the trade using the [orders](https://docs.sfox.com/orders#place-new-order) endpoint.

In the orders request, you will need to specify the same:

* `currency_pair`
* `quantity`
* `quote_id`&#x20;
* and, if specified in the quote request, the `client_quote_id`

{% hint style="info" %}
Quote requests are rate limited to 10 requests per second.
{% endhint %}

### Request Body

<table><thead><tr><th width="247">Name</th><th width="123">Type</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>pair</code></strong> <mark style="color:red;">required</mark></td><td>string</td><td>The currency pair for the quote. e.g. <code>btcusd</code></td></tr><tr><td><strong><code>side</code></strong> <mark style="color:red;">required</mark></td><td>string</td><td><p>The side for the quote (whether you are buying or selling). Possible values:</p><ul><li><code>buy</code> : You want to buy</li><li><code>sell</code>: You want to sell</li></ul></td></tr><tr><td><strong><code>quantity</code></strong> <mark style="color:red;">required</mark></td><td>number</td><td>The base currency quantity for the quote (e.g. <code>10</code> ). <strong>Must be &#x3C;= the maximum quote quantity for the given pair.</strong></td></tr><tr><td><strong><code>amount</code></strong></td><td>number</td><td>The quote currency quantity for the quote (e.g. <code>300000.0000</code> ). <strong>Required if</strong> <code>quantity</code> <strong>is not included in the request.</strong></td></tr><tr><td><strong><code>client_quote_id</code></strong></td><td>string</td><td>An optional idempotent identifier for your quote. <strong>If specified, you must specify the same value in the</strong> <code>client_order_id</code> <strong>field of your order request to execute on the quote.</strong></td></tr></tbody></table>

### Response Body

<table data-full-width="false"><thead><tr><th width="238.33333333333331">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>quote_id</code></strong></td><td>Unique identifier for the quote. <strong>Note</strong>: to execute an order on this quote you will specify this <code>quote_id</code> in your <a href="../orders#place-new-order">order request</a></td></tr><tr><td><strong><code>quantity</code></strong></td><td>The base currency quantity of the quote</td></tr><tr><td><strong><code>amount</code></strong></td><td>The quote currency amount of the quote</td></tr><tr><td><strong><code>pair</code></strong></td><td>The currency pair for the quote request</td></tr><tr><td><strong><code>side</code></strong></td><td>The quote side–whether you are buying or selling</td></tr><tr><td><strong><code>date_expiry</code></strong></td><td>The datetime the quote will expire</td></tr><tr><td><strong><code>date_quote</code></strong></td><td>The datetime the quote was generated</td></tr><tr><td><strong><code>buy_price</code></strong></td><td>The quote price–the price to buy this quantity. Returned if <code>side</code> = <code>buy</code>, else not included.</td></tr><tr><td><strong><code>sell_price</code></strong></td><td>The quote price–the price to sell this quantity. Returned if <code>side</code> = <code>sell</code>, else not included.</td></tr></tbody></table>

### Responses

<details>

<summary><mark style="color:green;">201</mark></summary>

```json
{
    "quote_id": "165c404c-ffe9-11ed-b8ed-0a170e3de1bd",
    "pair": "btcusd",
    "side": "BUY",
    "date_expiry": "2023-05-31T19:26:58.595Z",
    "date_quote": "2023-05-31T19:26:48.595Z",
    "amount": 27044.7156,
    "quantity": 1,
    "buy_price": 27044.7156
}
```

</details>

<details>

<summary><mark style="color:red;">422</mark>: Unprocessable Entity</summary>

{% code overflow="wrap" %}

```json
//Requested quote size greater than maximum quote size for the currency pair
{
    "error": "request USD value <USD_VALUE_OF_REQUESTED_QUOTE_SIZE> greater than max USD value <MAX_USD_VALUE> for pair <CURRENCY_PAIR>"
}

//Currency pair not currently supported for RFQ
{
    "error": "<CURRENCY_PAIR> not currently supported for RFQ. please contact support for more information."
}
```

{% endcode %}

</details>

<details>

<summary><mark style="color:red;">503</mark>: Service Unavailable</summary>

{% code overflow="wrap" %}

```json
//RFQ requests are temporarily unavailable
{
    "error": "quotes temporarily unavailable. please try again later."
}

//RFQ requests are temporarily unavailable for this currency pair
{
    "error": "<CURRENCY_PAIR> quotes temporarily unavailable. please try again later."
}
```

{% endcode %}

</details>

### Example Request

{% tabs %}
{% tab title="Shell" %}

```bash
curl -X POST \
  -H 'Content-type: application/json' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  --data '{ "pair": "btcusd",
            "side": "buy",
            "quantity": 1 }'  \
  'https://api.sfox.com/v1/quote'
```

{% endtab %}

{% tab title="NodeJS" %}

```javascript
const axios = require('axios');

axios({
  method: 'post',
  url: 'https://api.sfox.com/v1/quote',
  headers: {
    'Authorization': 'Bearer <API_KEY>'
  },
  data: {
   pair: 'btcusd',
   side: 'buy',
   quantity: 1
  }
}).then(response => {
  console.log(response)
}).catch(err => {
  console.error(err)
});
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

data = requests.post(
  "https://api.sfox.com/v1/quote",
  headers={
    "Authorization": "Bearer <API_KEY>",
  },
  data={
    "pair": "btcusd",
    "side": "buy",
    "quantity": 1
  }
)
print(data)
```

{% endtab %}
{% endtabs %}

## End-to-End Example

The following example details the end-to-end process of requesting a quote from the RFQ endpoint and executing an order to trade on that quote

### RFQ

* **Request**: Requested a quote to purchase 1 BTC on the BTC/USD pair
* **Response**: Received a purchase price of `23243.49136824` for 1 BTC with Quote ID `cb436399-9db7-11ed-8ea6-0e5724aafd6b` which is later specified in the order

  request

<table data-header-hidden data-full-width="false"><thead><tr><th width="138"></th><th></th></tr></thead><tbody><tr><td><strong>Request</strong></td><td><pre class="language-bash" data-overflow="wrap"><code class="lang-bash">curl -X POST \
  -H 'Content-type: application/json' \ 
  -H 'Authorization: Bearer &#x3C;API_TOKEN>' \ 
  --data '{ "pair": “btcusd”,
            "side": "buy",
            “quantity”: 1 }' \ 
'https://api.sfox.com/v1/quote'
</code></pre></td></tr><tr><td><strong>Response</strong></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">{
<strong>  "quote_id": "cb436399-9db7-11ed-8ea6-0e5724aafd6b", 
</strong>  "quantity": 1,
  "pair": "btcusd",
  "side": "BUY",
  "date_expiry": "2023-01-26T20:27:18.310Z", 
  "date_quote": "2023-01-26T20:27:03.310Z", 
  "buy_price": 23243.49136824
}
</code></pre></td></tr></tbody></table>

### Order Execution

* **Request**: Placed an order to buy 1 BTC on the BTC/USD pair and specified the previously received quote ID `cb436399-9db7-11ed-8ea6-0e5724aafd6b`
* **Response**: Received an “Order Filled” response, purchasing 1 BTC at the previously quoted unit price of `23243.49136824`

{% hint style="info" %}

* RFQ orders are Fill-or-Kill (FOK): Will be responded to with a “Done” (filled) or “Canceled” (rejected) order. The entire quantity will be filled or none at all
* Receive synchronous response: The response will reflect a terminal state of an order
* Are not guaranteed to be filled if placed within the quote expiry
* Only one order will be accepted per quote
* The order quantity must be less than or equal to the quote quantity
* Will settle immediately to your sFOX account if filled
  {% endhint %}

<table data-header-hidden data-full-width="false"><thead><tr><th width="173"></th><th></th></tr></thead><tbody><tr><td><strong>Request</strong></td><td><pre class="language-bash" data-overflow="wrap"><code class="lang-bash">curl -X POST \
  -H 'Content-type: application/json' \ 
  -H 'Authorization: Bearer &#x3C;API_TOKEN>' \ 
  --data '{ "currency_pair": “btcusd”,
            "quantity": 1,
            "quote_id": "cb436399-9db7-11ed-8ea6-0e5724aafd6b" }' \ 
      'https://api.sfox.com/v1/orders/buy'
</code></pre></td></tr><tr><td><strong>Response</strong></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">{
  "id": 1754344,
  "side_id": 500,
  "action": "Buy",
  "algorithm_id": 150,
  "algorithm": "Instant",
  "type": "Instant",
  "pair": "btcusd",
<strong>  "quantity": 1,
</strong>  "price": 23243.49136824,
  "amount": 0,
  "net_market_amount": 0,
  "filled": 1,
  "vwap": 23243.49136824,
  "filled_amount": 23243.49136824,
  "fees": 0,
  "net_proceeds": -23243.49136824,
  "status": "Done",
  "status_code": 300,
  "routing_option": "BestPrice",
  "routing_type": "None",
  "time_in_force": "FOK",
  "expires": null,
  "dateupdated": "2023-01-26T20:27:06.000Z", "client_order_id": "",
  "user_tx_id": "",
  "o_action": "Buy",
  "algo_id": 150,
  "algorithm_options": null,
  "destination": "",
  "quote_id": "cb436399-9db7-11ed-8ea6-0e5724aafd6b"
}
</code></pre></td></tr></tbody></table>