NAV Navbar
python javascript

API Change Log

23rd January 2025

14 November 2024

12 September 2024

29 August 2024

18 July 2024

4 July 2024

4 March 2024

2 April, 2024

5 October, 2023

28 September, 2023

3 April, 2023

24 Jan, 2023

13 Jan, 2023

15 Nov, 2022

4 March, 2022

Introduction

Welcome to the FalconX API documentation. The APIs provide developers programmatic access to FalconX services. In case of any questions please contact [email protected]

Trading Fees

Please reach out to your Relationship Manager to get a custom fee structure, based on your notional monthly traded volume.

REST API

Request For Quote (RFQ)

RFQ process involves the client sending details about the token pair they want to trade along with the quantity. FalconX RFQ API returns the price at which client can buy or sell the requested quantity in the requested token pair. The quote is valid only for a short period of time. If the client accepts the quote before it expires and FalconX sends a confirmation then the trade is considered closed.

API Clients

Python3 Client

Installation

pip3 install falconx

# Client example
from falconx import FalconxClient

client = FalconxClient(key=KEY, secret=SECRET, passphrase=PASSPHRASE)
quote = client.get_quote('BTC', 'USD', 5, 'two_way')
result = client.execute_quote(quote['fx_quote_id'], 'buy')

JavaScript Client

Installation

npm install falconx-node

// Client Example
const FalconxClient = require('falconx-node');

client = new FalconxClient(apiKey=KEY, secretKey=SECRET, passphrase=PASSPHRASE);
client.getQuote('BTC', 'USD', 5, 'two_way').then((quote) => {
  client.executeQuote(quote['fx_quote_id'], 'buy').then(response => console.log(response));
});

Requests

All requests and responses are application/json content type and follow typical HTTP response status codes for success and failure.

API Endpoint

Success

A successful response is indicated by HTTP status code 200 and may contain an optional body. If the response has a body it will be documented under each resource below.

Common HTTP error codes

Status Code Reason
400 Bad Request – Invalid request format
401 Unauthorized – Invalid API Key
401 Authentication Failed. Please check your credentials
403 Forbidden – You do not have access to the requested resource
404 Resource Not Found
500 Internal Server Error – We had a problem with our server

FalconX API Errors

Error Code Reason
ZERO_QUANTITY You cannot request a quantity of zero.
TRADING_DISABLED All trading has been disabled at FalconX at this time and we are not currently accepting quote or execution requests.
QUOTE_NOT_AVAILABLE Our partners were unable to provide a quote.
PARTNER_FAILURE Our partners failed to return a quote.
THIN_ORDERBOOK Our partners' orderbooks were too thin to provide you a quote.
MAX_USD_SIZE_LIMIT You have surpassed the maximum value in USD for which we can provide a quote at this time.
INTERNAL_ERROR Our internal server returned an error.
QUANTITY_TOO_SMALL The quantity you requested is below our platform's minimum trading limit. Please contact your relationship manager to have this modified if required.
QUANTITY_TOO_BIG The quantity you requested is above our platform's maximum trading limit. Please contact your relationship manager to have this modified if required.
QUOTE_EXPIRED The trade was not executed because the quote expired.
ACCOUNT_DISABLED Your account has not yet been approved for trading.
ACCOUNT_READ_ONLY Your account has read-only permission, but does not have permission to trade.
INVALID_QUOTE_ID The given quote ID is invalid.
INSUFFICIENT_BALANCE You do not have sufficient balance to execute this trade.
RETRY_ERROR You cannot execute the same quote twice. The provided quote is under process or already executed.
PERMISSION_DENIED You have insufficient permission to access the quote.
MARKET_NOT_ALLOWED You do not have access to the requested market.
MIN_TRADE_LIMIT_BREACH The trade was not executed because the quantity you requested is less than the minimum allowed.
MAX_TRADE_LIMIT_BREACH The trade was not executed because the quantity you requested is greater than the maximum allowed.
MIN_QUOTE_LIMIT_BREACH Requested quote size is less than the minimum allowed.
MAX_QUOTE_LIMIT_BREACH Requested quote size is greater than the minimum allowed.
TRADE_NOT_FILLED Your trade was not executed.
MAX_NET_BREACHED Your trade was not executed because you hit your max net outstanding limit.
MAX_GROSS_BREACHED Your trade was not executed because you hit your max gross outstanding limit.
QUOTE_EXPIRED_MARKET_VOLATILITY Your trade was not executed because the quote expired early due to market volatility.
UNAUTHORIZED You are not authorized to access this resource.
NO_VALID_EXECUTABLE_QUOTE Your trade was not executed because it was no longer a valid executable quote. The quote was expired early due to market volatility.
EXECUTION_PENDING Trade execution is in progress.
PER_SECOND_RATE_LIMIT Number of requests per second exceeded the per second rate limit.
PER_MINUTE_RATE_LIMIT Number of requests per minute exceeded the per minute rate limit.
PER_HOUR_RATE_LIMIT Number of requests per hour exceeded the per hour rate limit.
API_KEY_DISABLED Your API Key is pending approval by FalconX.
REQUEST_IP_RESTRICTED Your IP is not whitelisted to access our APIs.
WHITELISTED_API_ENDPOINT Your account does not have access to this endpoint.
INVALID_DATE_FORMAT The input requires an ISO date format.
INSUFFICIENT_PARAMETERS_PROVIDED The number of parameters provided are insufficient.
START_DATE_AFTER_END_DATE The start date cannot be after end date.
INSUFFICIENT_BALANCE_TO_WITHDRAW Withdrawal balance should be less than or equal to the balance in account.
INVALID_WITHDRAWAL_AMOUNT Requested withdrawal amount is invalid.

Authentication

Generating an API Key

Once you are signed up on FalconX, our customer success team will generate an API key for you. After generating the key you will have the following information which will be required for making any API request:

Creating a Request

# python version: v3.6.7
#
# Requires python-requests, python-socketio, python-engineio Install with pip:
#
#   pip3 install requests==2.20.0, python-socketio==4.6.0, python-engineio==3.12.1
#
# or, with easy-install:
#
#   easy_install requests==2.20.0

import json, hmac, hashlib, time, requests, base64
from requests.auth import AuthBase

# Create custom authentication for RFQ
class FXRfqAuth(AuthBase):
    def __init__(self, api_key, secret_key, passphrase):
        self.api_key = api_key
        self.secret_key = secret_key
        self.passphrase = passphrase

    def __call__(self, request):
        timestamp = str(time.time())
        request_body = request.body.decode() if request.body else ''
        message = timestamp + request.method + request.path_url + request_body
        hmac_key = base64.b64decode(self.secret_key)
        signature = hmac.new(hmac_key, message.encode(), hashlib.sha256)
        signature_b64 = base64.b64encode(signature.digest())

        request.headers.update({
            'FX-ACCESS-SIGN': signature_b64,
            'FX-ACCESS-TIMESTAMP': timestamp,
            'FX-ACCESS-KEY': self.api_key,
            'FX-ACCESS-PASSPHRASE': self.passphrase,
            'Content-Type': 'application/json'
        })
        return request


api_url = 'https://api.falconx.io/v1/'
auth = FXRfqAuth(API_KEY, API_SECRET, API_PASS)

# Get Quote
params = {
    'token_pair': {
      'base_token': 'BTC',
      'quote_token': 'USD'
    },
    'quantity': {
      'token': 'BTC',
      'value': 10
    },
    'side': 'buy'
}

r = requests.post(api_url + 'quotes', json=params, auth=auth)
print(r.json())
# {"status": "success", "fx_quote_id": "00c884b056f949338788dfb59e495377"...}

All REST API requests must contain the following headers:

All request bodies should have content type application/json and should be a valid JSON.

Signing a Message

The FX-ACCESS-SIGN header is generated by creating a sha256 HMAC using the base64-decoded secret key on the prehash string timestamp + method + requestPath + body (where + represents string concatenation) and base64-encode the output. The timestamp value is the same as the FX-ACCESS-TIMESTAMP header.

The body is the request body string or omitted if there is no request body (typically for GET requests).

The method should be UPPER CASE.

Remember to first base64-decode the alphanumeric secret string before using it as the key for HMAC. Also, base64-encode the digest output before sending in the header.

Selecting a Timestamp

The FX-ACCESS-TIMESTAMP header must be number of seconds since Unix Epoch in UTC. Decimal values are allowed.

Your timestamp must be within 30 seconds of the API service time or your request will be considered expired and rejected.

Get Token Pairs

Get the list of all token pairs currently supported.

HTTP Request

Request Sample

# substitute placeholders with correct authorization header values
curl -X GET "https://api.falconx.io/v1/pairs" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"

GET https://api.falconx.io/v1/pairs

Response Parameters

Response Sample

[
  {
    "base_token": "BTC",
    "quote_token": "USD"
  },
  {
    "base_token": "ETH",
    "quote_token": "USD"
  }
]

API will return a list of Token Pair JSON structure.

Client Order ID

Client Order ID is a client-generated tag that can be assigned to an order or group of orders. It's not required and can be duplicated for rfq and market/fok orders. FalconX will return the tag in all subsequent responses about that order/quote.

Allowed characters

Characters Description ASCII Code (Decimal)
A-Z Uppercase A-Z 65-90
a-z Lowercase a-z 97-122
0-9 Numbers 48-57
- Dash 45
_ Underscore 95
. Full stop 46
: Colon 58

Client Order UUID

Client Order UUID is a client-generated universally unique identifier for rfq and market/fok orders. FalconX will return in all subsequent responses about that order/quote.

Allowed characters

Characters Description ASCII Code (Decimal)
A-Z Uppercase A-Z 65-90
a-z Lowercase a-z 97-122
0-9 Numbers 48-57
- Dash 45
_ Underscore 95
. Full stop 46
: Colon 58

[Deprecated] Get Quote

Client sends request to get quote to this endpoint. The response contains the timestamp until which the quote is valid. Only a valid quote can be executed.

HTTP Request

POST https://api.falconx.io/v1/quotes

Request Body

Request Sample

{
  "token_pair": {
    "base_token": "BTC",
    "quote_token": "USD"
  },
  "quantity": {
    "token": "BTC",
    "value": "10"
  },
  "side": "buy",
  "client_order_id": "d6f3e1fa-e148-4009-9c07-a87f9ae78d1a"
}
Parameter Type Description
token_pair JSON Token pair for which the client is requesting quote (See Token Pair)
quantity JSON Requested quantity upto 8 decimal places (See Quantity)
side STRING Side of quote. Possible values: buy, sell or two_way
client_order_id STRING [optional] Tag generated by the client for the quote/order (See Client Order ID)

Response Parameters

Response Sample

{
  "status": "success",
  "fx_quote_id": "00c884b056f949338788dfb59e495377",
  "client_order_id": "order-group-1",
  "buy_price": 12650,
  "sell_price": null,
  "token_pair": {
    "base_token": "BTC",
    "quote_token": "USD"
  },
  "quantity_requested": {
    "token": "BTC",
    "value": "10"
  },
  "position_in": {
    "token" : "BTC",
    "value": 10
  },
  "position_out" : {
    "token": "USD",
    "value": 12650
  },
  "side_requested": "buy",
  "t_quote": "2019-06-27T11:59:21.875725+00:00",
  "t_expiry": "2019-06-27T11:59:22.875725+00:00",
  "t_execute": null,
  "is_filled": false,
  "gross_fee_bps": 8,
  "gross_fee_usd": 101.20,
  "rebate_bps": 3,
  "rebate_usd": 37.95,
  "fee_bps": 5,
  "fee_usd": 63.25,
  "side_executed": null,
  "platform": "browser",
  "trader_email": "[email protected]",
  "warnings": [
    {
        "code": "MAX_NET_BREACH",
        "is_blocking": true,
        "message": "Trade exceeds net limit, contact FalconX",
        "priority": 2,
        "side": "buy"
    },
    {
        "code": "MAX_NET_BREACH",
        "is_blocking": true,
        "message": "Trade exceeds net limit, contact FalconX",
        "priority": 2,
        "side": "sell"
    }
  ],
  "order_type": "rfq",
  "error": null
}
Parameter Type Description
status STRING Status of the response. Possible values: success or failure
fx_quote_id STRING FalconX Quote ID. Use this when executing quote
client_order_id STRING Tag generated by the client for the quote/order
buy_price DECIMAL Buy price in quote token
sell_price DECIMAL Sell price in quote token
token_pair JSON Token pair for which the client is requesting quote (See Token Pair)
quantity_requested JSON Requested quantity (See Quantity)
position_in JSON Amount to be received by the user (See Price)
position_out JSON Amount to be received by FalconX (See Price)
side_requested STRING Side of quote. Possible values: buy, sell or two_way
t_quote STRING Quote time in ISO 8601 date format
t_expiry STRING Quote expiry time in ISO 8601 date format
t_execute STRING Quote execution time in ISO 8601 date format. null for quotes endpoint
is_filled BOOLEAN true if quote has been executed successfully else false. false for quote request
gross_fee_bps DECIMAL Fee in basis points applicable on trade execution
gross_fee_usd DECIMAL Fee in USD notional applicable on trade execution
rebate_bps DECIMAL Rebate in basis points applicable on trade execution
rebate_usd DECIMAL Rebate in USD notional applicable on trade execution
fee_bps DECIMAL Effective Fee in basis points applicable on trade execution. Difference between gross_fee_bps and rebate_bps
fee_usd DECIMAL Effective Fee in USD notional applicable on trade execution. Difference between gross_fee_usd and rebate_usd
side_executed STRING Side of quote executed. null for quote request
platform STRING Trading platform used for getting quote
trader_email STRING Email address of the trader
warnings JSON Array of Warnings (see Warning). Will be an empty array if no warnings.
order_type STRING rfq
error JSON Error info. null if no error (see Error)

[Deprecated] Execute Quote

Execute quote fetched in the Get Quote API call.

HTTP Request

POST https://api.falconx.io/v1/quotes/execute

Request Body

Request Sample

{
    "fx_quote_id": "00c884b056f949338788dfb59e495377",
    "side": "buy",
    "client_order_uuid": "b006d50d-c1cb-4ddd-9429-782b7a4c3864",
}
Parameter Type Description
fx_quote_id STRING FalconX Quote ID fetched in the Get Quote API call
side STRING Side of quote. Possible values: buy or sell
client_order_uuid STRING [optional] Client Order UUID (See Client Order UUID)

Response Parameters

Response Sample

{
  "status": "success",
  "fx_quote_id": "00c884b056f949338788dfb59e495377",
  "client_order_id": "order-group-1",
  "client_order_uuid": "b006d50d-c1cb-4ddd-9429-782b7a4c3864",
  "buy_price": 12650,
  "sell_price": null,
  "token_pair": {
    "base_token": "BTC",
    "quote_token": "USD"
  },
  "quantity_requested": {
    "token": "BTC",
    "value": "10"
  },
  "position_in": {
    "token" : "BTC",
    "value": 10
  },
  "position_out" : {
    "token": "USD",
    "value": 12650
  },
  "side_requested": "buy",
  "t_quote": "2019-06-27T11:59:21.875725+00:00",
  "t_expiry": "2019-06-27T11:59:22.875725+00:00",
  "t_execute": "2019-06-27T11:59:21.875725+00:00",
  "is_filled": true,
  "gross_fee_bps": 8,
  "gross_fee_usd": 101.20,
  "rebate_bps": 3,
  "rebate_usd": 37.95,
  "fee_bps": 5,
  "fee_usd": 63.25,
  "side_executed": "buy",
  "order_type": "rfq",
  "error": null
}
Parameter Type Description
status STRING Status of the response. Possible values: success or failure or processing
fx_quote_id STRING FalconX Quote ID
client_order_id STRING Tag generated by the client for the quote/order
client_order_uuid STRING The unique identifier generated by the client to identify the quote/order
buy_price DECIMAL Buy price in quote token
sell_price DECIMAL Sell price in quote token
token_pair JSON Token pair for which the client is requesting quote (See Token Pair)
quantity_requested JSON Requested quantity (See Quantity)
position_in JSON Amount to be received by the user (See Price)
position_out JSON Amount to be received by FalconX (See Price)
side_requested STRING Side of quote. Possible values: buy, sell or two_way
t_quote STRING Quote time in ISO 8601 date format
t_expiry STRING Quote expiry time in ISO 8601 date format
t_execute STRING Quote execution time in ISO 8601 date format
is_filled BOOLEAN true if quote has been executed successfully else false
gross_fee_bps DECIMAL Fee in basis points applicable on trade execution
gross_fee_usd DECIMAL Fee in USD notional applicable on trade execution
rebate_bps DECIMAL Rebate in basis points applicable on trade execution
rebate_usd DECIMAL Rebate in USD notional applicable on trade execution
fee_bps DECIMAL Effective Fee in basis points applicable on trade execution. Difference between gross_fee_bps and rebate_bps
fee_usd DECIMAL Effective Fee in USD notional applicable on trade execution. Difference between gross_fee_usd and rebate_usd
side_executed STRING Side of quote executed
order_type STRING rfq
error JSON Error info. null if no error (see Error)

Note: In rare cases the execution status can be processing which means that it'll take us few seconds to verify the trade. In these cases keep checking status of the quote using Quote Status API until you receive success or failure status.

Quote Status

Get status of a quote by ID.

HTTP Request

GET https://api.falconx.io/v1/quotes/<fx_quote_id>

Path Parameters

Request Sample

# substitute placeholders with correct authorization header values
curl -X GET "https://api.falconx.io/v1/quotes/00c884b056f949338788dfb59e495377" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"
Parameter Type Description
fx_quote_id STRING FalconX Quote ID fetched in the Get Quote API call

Response Parameters

Response Sample

{
  "status": "success",
  "fx_quote_id": "00c884b056f949338788dfb59e495377",
  "client_order_id": "order-group-1",
  "client_order_uuid": "b006d50d-c1cb-4ddd-9429-782b7a4c3864",
  "buy_price": 12650,
  "sell_price": null,
  "platform": "api",
  "token_pair": {
    "base_token": "BTC",
    "quote_token": "USD"
  },
  "quantity_requested": {
    "token": "BTC",
    "value": "10"
  },
  "position_in": {
    "token" : "BTC",
    "value": 10
  },
  "position_out" : {
    "token": "USD",
    "value": 12650
  },
  "side_requested": "buy",
  "t_quote": "2019-06-27T11:59:21.875725+00:00",
  "t_expiry": "2019-06-27T11:59:22.875725+00:00",
  "t_execute": "2019-06-27T11:59:22.875725+00:00",
  "is_filled": true,
  "gross_fee_bps": 8,
  "gross_fee_usd": 101.20,
  "rebate_bps": 3,
  "rebate_usd": 37.95,
  "fee_bps": 5,
  "fee_usd": 63.25,
  "side_executed": "buy",
  "trader_email": "[email protected]",
  "warnings": [],
  "order_type": "rfq",
  "error": null
}
Parameter Type Description
status STRING Status of the response. Possible values: success or failure
fx_quote_id STRING FalconX Quote ID
client_order_id STRING Tag generated by the client for the quote/order
client_order_uuid STRING The unique identifier generated by the client to identify the quote/order
buy_price DECIMAL Buy price in quote token
sell_price DECIMAL Sell price in quote token
platform STRING Platform for quote. Possible values: api, browser or margin
token_pair JSON Token pair for which the client is requesting quote (See Token Pair)
quantity_requested JSON Requested quantity (See Quantity)
position_in JSON Amount to be received by the user (See Price)
position_out JSON Amount to be received by FalconX (See Price)
side_requested STRING Side of quote. Possible values: buy, sell or two_way
t_quote STRING Quote time in ISO 8601 date format
t_expiry STRING Quote expiry time in ISO 8601 date format
t_execute STRING Quote execution time in ISO 8601 date format
is_filled BOOLEAN true if quote has been executed successfully else false
gross_fee_bps DECIMAL Fee in basis points applicable on trade execution
gross_fee_usd DECIMAL Fee in USD notional applicable on trade execution
rebate_bps DECIMAL Rebate in basis points applicable on trade execution
rebate_usd DECIMAL Rebate in USD notional applicable on trade execution
fee_bps DECIMAL Effective Fee in basis points applicable on trade execution. Difference between gross_fee_bps and rebate_bps
fee_usd DECIMAL Effective Fee in USD notional applicable on trade execution. Difference between gross_fee_usd and rebate_usd
side_executed STRING Side of quote executed. null if not executed
trader_email STRING Email of trader who requested the quote
warnings JSON Array of Warnings (see Warning). Will be an empty array if no warnings.
order_type STRING rfq
error JSON Error info. null if no error (see Error)

Get Quote (New V3 Endpoint)

Client sends request to get quote to this endpoint. The response contains the timestamp until which the quote is valid. Only a valid quote can be executed.

HTTP Request

POST https://api.falconx.io/v3/quotes Please Note - endpoint has v3 (not v1)

Request Body

Request Sample

{
  "token_pair": {
    "base_token": "BTC",
    "quote_token": "USD"
  },
  "quantity": {
    "token": "BTC",
    "value": "10"
  },
  "side": "buy",
  "client_order_id": "d6f3e1fa-e148-4009-9c07-a87f9ae78d1a"
}
Parameter Type Description
token_pair JSON Token pair for which the client is requesting quote (See Token Pair)
quantity JSON Requested quantity upto 8 decimal places (See Quantity)
side STRING Side of quote. Possible values: buy, sell or two_way
client_order_id STRING [optional] Tag generated by the client for the quote/order (See Client Order ID)

Response Parameters

Response Sample

{
  "status": "success",
  "fx_quote_id": "00c884b056f949338788dfb59e495377",
  "client_order_id": "order-group-1",
  "buy_price": 12650,
  "sell_price": null,
  "token_pair": {
    "base_token": "BTC",
    "quote_token": "USD"
  },
  "quantity_requested": {
    "token": "BTC",
    "value": "10"
  },
  "position_in": {
    "token" : "BTC",
    "value": 10
  },
  "position_out" : {
    "token": "USD",
    "value": 12650
  },
  "side_requested": "buy",
  "t_quote": "2019-06-27T11:59:21.875725+00:00",
  "t_expiry": "2019-06-27T11:59:22.875725+00:00",
  "t_execute": null,
  "is_filled": false,
  "gross_fee_bps": 8,
  "gross_fee_usd": 101.20,
  "rebate_bps": 3,
  "rebate_usd": 37.95,
  "fee_bps": 5,
  "fee_usd": 63.25,
  "side_executed": null,
  "platform": "browser",
  "trader_email": "[email protected]",
  "warnings": [
    {
        "code": "MAX_NET_BREACH",
        "is_blocking": true,
        "message": "Trade exceeds net limit, contact FalconX",
        "priority": 2,
        "side": "buy"
    },
    {
        "code": "MAX_NET_BREACH",
        "is_blocking": true,
        "message": "Trade exceeds net limit, contact FalconX",
        "priority": 2,
        "side": "sell"
    }
  ],
  "order_type": "rfq",
  "error": null
}
Parameter Type Description
status STRING Status of the response. Possible values: success or failure
fx_quote_id STRING FalconX Quote ID. Use this when executing quote
client_order_id STRING Tag generated by the client for the quote/order
buy_price DECIMAL Buy price in quote token
sell_price DECIMAL Sell price in quote token
token_pair JSON Token pair for which the client is requesting quote (See Token Pair)
quantity_requested JSON Requested quantity (See Quantity)
position_in JSON Amount to be received by the user (See Price)
position_out JSON Amount to be received by FalconX (See Price)
side_requested STRING Side of quote. Possible values: buy, sell or two_way
t_quote STRING Quote time in ISO 8601 date format
t_expiry STRING Quote expiry time in ISO 8601 date format
t_execute STRING Quote execution time in ISO 8601 date format. null for quotes endpoint
is_filled BOOLEAN true if quote has been executed successfully else false. false for quote request
gross_fee_bps DECIMAL Fee in basis points applicable on trade execution
gross_fee_usd DECIMAL Fee in USD notional applicable on trade execution
rebate_bps DECIMAL Rebate in basis points applicable on trade execution
rebate_usd DECIMAL Rebate in USD notional applicable on trade execution
fee_bps DECIMAL Effective Fee in basis points applicable on trade execution. Difference between gross_fee_bps and rebate_bps
fee_usd DECIMAL Effective Fee in USD notional applicable on trade execution. Difference between gross_fee_usd and rebate_usd
side_executed STRING Side of quote executed. null for quote request
platform STRING Trading platform used for getting quote
trader_email STRING Email address of the trader
warnings JSON Array of Warnings (see Warning). Will be an empty array if no warnings.
order_type STRING rfq
error JSON Error info. null if no error (see Error)

Execute Quote (New V3 Endpoint)

Execute quote fetched in the Get Quote API call.

HTTP Request

POST https://api.falconx.io/v3/quotes/execute

Request Body

Request Sample

{
    "fx_quote_id": "00c884b056f949338788dfb59e495377",
    "side": "buy",
    "client_order_uuid": "b006d50d-c1cb-4ddd-9429-782b7a4c3864",
}
Parameter Type Description
fx_quote_id STRING FalconX Quote ID fetched in the Get Quote API call
side STRING Side of quote. Possible values: buy or sell
client_order_uuid STRING [optional] Client Order UUID (See Client Order UUID)

Response Parameters

Response Sample

{
  "status": "success",
  "fx_quote_id": "00c884b056f949338788dfb59e495377",
  "client_order_id": "order-group-1",
  "client_order_uuid": "b006d50d-c1cb-4ddd-9429-782b7a4c3864",
  "buy_price": 12650,
  "sell_price": null,
  "token_pair": {
    "base_token": "BTC",
    "quote_token": "USD"
  },
  "quantity_requested": {
    "token": "BTC",
    "value": "10"
  },
  "position_in": {
    "token" : "BTC",
    "value": 10
  },
  "position_out" : {
    "token": "USD",
    "value": 12650
  },
  "side_requested": "buy",
  "t_quote": "2019-06-27T11:59:21.875725+00:00",
  "t_expiry": "2019-06-27T11:59:22.875725+00:00",
  "t_execute": "2019-06-27T11:59:21.875725+00:00",
  "is_filled": true,
  "gross_fee_bps": 8,
  "gross_fee_usd": 101.20,
  "rebate_bps": 3,
  "rebate_usd": 37.95,
  "fee_bps": 5,
  "fee_usd": 63.25,
  "side_executed": "buy",
  "order_type": "rfq",
  "error": null
}
Parameter Type Description
status STRING Status of the response. Possible values: success or failure or processing
fx_quote_id STRING FalconX Quote ID
client_order_id STRING Tag generated by the client for the quote/order
client_order_uuid STRING The unique identifier generated by the client to identify the quote/order
buy_price DECIMAL Buy price in quote token
sell_price DECIMAL Sell price in quote token
token_pair JSON Token pair for which the client is requesting quote (See Token Pair)
quantity_requested JSON Requested quantity (See Quantity)
position_in JSON Amount to be received by the user (See Price)
position_out JSON Amount to be received by FalconX (See Price)
side_requested STRING Side of quote. Possible values: buy, sell or two_way
t_quote STRING Quote time in ISO 8601 date format
t_expiry STRING Quote expiry time in ISO 8601 date format
t_execute STRING Quote execution time in ISO 8601 date format
is_filled BOOLEAN true if quote has been executed successfully else false
gross_fee_bps DECIMAL Fee in basis points applicable on trade execution
gross_fee_usd DECIMAL Fee in USD notional applicable on trade execution
rebate_bps DECIMAL Rebate in basis points applicable on trade execution
rebate_usd DECIMAL Rebate in USD notional applicable on trade execution
fee_bps DECIMAL Effective Fee in basis points applicable on trade execution. Difference between gross_fee_bps and rebate_bps
fee_usd DECIMAL Effective Fee in USD notional applicable on trade execution. Difference between gross_fee_usd and rebate_usd
side_executed STRING Side of quote executed
order_type STRING rfq
error JSON Error info. null if no error (see Error)

Note: In rare cases the execution status can be processing which means that it'll take us few seconds to verify the trade. In these cases keep checking status of the quote using Quote Status API until you receive success or failure status.

Quote Status (Using client_order_uuid)

Get status of a quote by client_order_uuid.

HTTP Request

GET https://api.falconx.io/v1/quotes/client_order_uuid/<client_order_uuid>

Path Parameters

Request Sample

# substitute placeholders with correct authorization header values
curl -X GET "https://api.falconx.io/v1/quotes/client_order_uuid/b006d50d-c1cb-4ddd-9429-782b7a4c3864" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"
Parameter Type Description
client_order_uuid STRING The unique identifier generated by the client to identify the quote/order

Response Parameters

Response Sample

{
  "status": "success",
  "fx_quote_id": "00c884b056f949338788dfb59e495377",
  "client_order_id": "order-group-1",
  "client_order_uuid": "b006d50d-c1cb-4ddd-9429-782b7a4c3864",
  "buy_price": 12650,
  "sell_price": null,
  "platform": "api",
  "token_pair": {
    "base_token": "BTC",
    "quote_token": "USD"
  },
  "quantity_requested": {
    "token": "BTC",
    "value": "10"
  },
  "position_in": {
    "token" : "BTC",
    "value": 10
  },
  "position_out" : {
    "token": "USD",
    "value": 12650
  },
  "side_requested": "buy",
  "t_quote": "2019-06-27T11:59:21.875725+00:00",
  "t_expiry": "2019-06-27T11:59:22.875725+00:00",
  "t_execute": "2019-06-27T11:59:22.875725+00:00",
  "is_filled": true,
  "gross_fee_bps": 8,
  "gross_fee_usd": 101.20,
  "rebate_bps": 3,
  "rebate_usd": 37.95,
  "fee_bps": 5,
  "fee_usd": 63.25,
  "side_executed": "buy",
  "trader_email": "[email protected]",
  "warnings": [],
  "order_type": "rfq",
  "error": null
}
Parameter Type Description
status STRING Status of the response. Possible values: success or failure
fx_quote_id STRING FalconX Quote ID
client_order_id STRING Tag generated by the client for the quote/order
client_order_uuid STRING The unique identifier generated by the client to identify the quote/order
buy_price DECIMAL Buy price in quote token
sell_price DECIMAL Sell price in quote token
platform STRING Platform for quote. Possible values: api, browser or margin
token_pair JSON Token pair for which the client is requesting quote (See Token Pair)
quantity_requested JSON Requested quantity (See Quantity)
position_in JSON Amount to be received by the user (See Price)
position_out JSON Amount to be received by FalconX (See Price)
side_requested STRING Side of quote. Possible values: buy, sell or two_way
t_quote STRING Quote time in ISO 8601 date format
t_expiry STRING Quote expiry time in ISO 8601 date format
t_execute STRING Quote execution time in ISO 8601 date format
is_filled BOOLEAN true if quote has been executed successfully else false
gross_fee_bps DECIMAL Fee in basis points applicable on trade execution
gross_fee_usd DECIMAL Fee in USD notional applicable on trade execution
rebate_bps DECIMAL Rebate in basis points applicable on trade execution
rebate_usd DECIMAL Rebate in USD notional applicable on trade execution
fee_bps DECIMAL Effective Fee in basis points applicable on trade execution. Difference between gross_fee_bps and rebate_bps
fee_usd DECIMAL Effective Fee in USD notional applicable on trade execution. Difference between gross_fee_usd and rebate_usd
side_executed STRING Side of quote executed. null if not executed
trader_email STRING Email of trader who requested the quote
warnings JSON Array of Warnings (see Warning). Will be an empty array if no warnings.
order_type STRING rfq
error JSON Error info. null if no error (see Error)

Get Executed Quotes

Get executed quotes between the given time range. Time range should be provided in ISO 8601 date format.

HTTP Request

GET https://api.falconx.io/v1/quotes

Query Parameters

Request Sample

# substitute placeholders with correct authorization header values
curl -X GET "https://api.falconx.io/v1/quotes" \
      --data-urlencode "t_start=2019-06-20T00:00:00+00:00" \
      --data-urlencode "t_end=2019-06-21T00:00:00+00:00" \
      --data-urlencode "platform=api" \
      --data-urlencode "status=success" \
      --data-urlencode "limit=1" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"
Parameter Type Description
t_start STRING Start of time range in ISO 8601 date format
t_end STRING End of time range in ISO 8601 date format
platform STRING Platform for quote. Possible values: api, browser or chat. If not present quotes from all platforms are returned
status STRING Filter by status. Possible values: success, failure or null. Default value: success. If null, all the trades will be returned.

Response Parameters

Response Sample

[
  {
    "status": "success",
    "fx_quote_id": "00c884b056f949338788dfb59e495377",
    "client_order_id": "order-group-1",
    "client_order_uuid": "b006d50d-c1cb-4ddd-9429-782b7a4c3864",
    "buy_price": 12650,
    "sell_price": null,
    "platform": "api",
    "token_pair": {
      "base_token": "BTC",
      "quote_token": "USD"
    },
    "quantity_requested": {
      "token": "BTC",
      "value": "10"
    },
    "position_in": {
      "token" : "BTC",
      "value": 10
    },
    "position_out" : {
      "token": "USD",
      "value": 12650
    },
    "side_requested": "buy",
    "t_quote": "2019-06-27T11:59:21.875725+00:00",
    "t_expiry": "2019-06-27T11:59:22.875725+00:00",
    "t_execute": "2019-06-27T11:59:22.875725+00:00",
    "is_filled": true,
    "gross_fee_bps": 8,
    "gross_fee_usd": 101.20,
    "rebate_bps": 3,
    "rebate_usd": 37.95,
    "fee_bps": 5,
    "fee_usd": 63.25,
    "side_executed": "buy",
    "trader_email": "[email protected]",
    "order_type": "rfq",
    "error": null
  }
]

API will return a list of the following structure:

Parameter Type Description
status STRING Status of the response. Possible values: success or failure
fx_quote_id STRING FalconX Quote ID
client_order_id STRING Tag generated by the client for the quote/order
client_order_uuid STRING The unique identifier generated by the client to identify the quote/order
buy_price DECIMAL Buy price in quote token
sell_price DECIMAL Sell price in quote token
platform STRING Platform for quote. Possible values: api, browser or margin
token_pair JSON Token pair for which the client is requesting quote (See Token Pair)
quantity_requested JSON Requested quantity (See Quantity)
position_in JSON Amount to be received by the user (See Price)
position_out JSON Amount to be received by FalconX (See Price)
side_requested STRING Side of quote. Possible values: buy, sell or two_way
t_quote STRING Quote time in ISO 8601 date format
t_expiry STRING Quote expiry time in ISO 8601 date format
t_execute STRING Quote execution time in ISO 8601 date format
is_filled BOOLEAN true if quote has been executed successfully else false
gross_fee_bps DECIMAL Fee in basis points applicable on trade execution
gross_fee_usd DECIMAL Fee in USD notional applicable on trade execution
rebate_bps DECIMAL Rebate in basis points applicable on trade execution
rebate_usd DECIMAL Rebate in USD notional applicable on trade execution
fee_bps DECIMAL Effective Fee in basis points applicable on trade execution. Difference between gross_fee_bps and rebate_bps
fee_usd DECIMAL Effective Fee in USD notional applicable on trade execution. Difference between gross_fee_usd and rebate_usd
side_executed STRING Side of quote executed
trader_email STRING Email of trader who requested the quote
order_type STRING Order type (rfq, market, limit or twap)
error JSON Error info. null if no error (see Error)

Order

Place market or limit order via REST API. We only support fok time in force for limit order_type over the REST API currently.

You can get the status of the order via Get Executed Quotes

HTTP Request

POST https://api.falconx.io/v3/order

Please Note - endpoint has v3 (not v1)

Query Parameters

Request Sample (Limit-FOK order)

{
  "token_pair": {
    "base_token": "BTC",
    "quote_token": "USD"
  },
  "quantity": {
    "token": "BTC",
    "value": 0.005
  },
  "side": "buy",
  "order_type": "limit",
  "time_in_force": "fok",
  "limit_price": 8547.11,
  "slippage_bps": 2,
  "client_order_id": "order-group-2-fok",
  "client_order_uuid": "b006d50d-c1cb-4ddd-9429-782b7a4c3864"
}

Request Sample (Market order)

{
  "token_pair": {
    "base_token": "BTC",
    "quote_token": "USD"
  },
  "quantity": {
    "token": "BTC",
    "value": 0.005
  },
  "side": "buy",
  "order_type": "market",
  "client_order_id": "order-group-2-market",
  "client_order_uuid": "b006d50d-c1cb-4ddd-9429-782b7a4c3865"
}
Parameter Type Description
token_pair JSON Token pair for which the client is placing the order (See Token Pair)
quantity JSON Requested quantity upto 8 decimal places (See Quantity)
side STRING Side of the order. Possible values: buy or sell
order_type STRING Order type. Possible values: market or limit
time_in_force STRING Time in force. Possible value: fok (required only when order_type is limit)
limit_price DECIMAL Limit price of the order in the units of quote_token (required only when order_type is limit)
slippage_bps DECIMAL [optional] Slippage (in bps) on the limit_price. (This parameter is only valid when order_type is limit)
client_order_id STRING [optional] Tag generated by the client for the quote/order (See Client Order ID)
client_order_uuid STRING [optional] Client Order UUID (See Client Order UUID)

Response Parameters

Response Sample (Limit-FOK order)

{
  "status": "success",
  "fx_quote_id": "00c884b056f949338788dfb59e495377",
  "client_order_id": "order-group-2-fok",
  "client_order_uuid": "b006d50d-c1cb-4ddd-9429-782b7a4c3864",
  "buy_price": 8545.12,
  "sell_price": null,
  "platform": "api",
  "token_pair": {
    "base_token": "BTC",
    "quote_token": "USD"
  },
  "quantity_requested": {
    "token": "BTC",
    "value": 10.0
  },
  "side_requested": "buy",
  "t_quote": "2019-06-27T11:59:21.875725+00:00",
  "t_expiry": null,
  "t_execute": "2019-06-27T11:59:21.875725+00:00",
  "is_filled": true,
  "gross_fee_bps": 8,
  "gross_fee_usd": 101.20,
  "rebate_bps": 3,
  "rebate_usd": 37.95,
  "fee_bps": 5,
  "fee_usd": 63.25,
  "side_executed": "buy",
  "trader_email": "[email protected]",
  "order_type": "limit",
  "time_in_force": "fok",
  "limit_price": 8547.11,
  "slippage_bps": 2,
  "error": null
}

Response Sample (Market order)

{
  "status": "success",
  "fx_quote_id": "00c884b056f949338788dfb59e495377",
  "client_order_id": "order-group-2-market",
  "client_order_uuid": "b006d50d-c1cb-4ddd-9429-782b7a4c3865",
  "buy_price": 8545.12,
  "sell_price": null,
  "platform": "api",
  "token_pair": {
    "base_token": "BTC",
    "quote_token": "USD"
  },
  "quantity_requested": {
    "token": "BTC",
    "value": 10.0
  },
  "side_requested": "buy",
  "t_quote": "2019-06-27T11:59:21.875725+00:00",
  "t_expiry": null,
  "t_execute": "2019-06-27T11:59:21.875725+00:00",
  "is_filled": true,
  "gross_fee_bps": 8,
  "gross_fee_usd": 101.20,
  "rebate_bps": 3,
  "rebate_usd": 37.95,
  "fee_bps": 5,
  "fee_usd": 63.25,
  "side_executed": "buy",
  "trader_email": "[email protected]",
  "order_type": "market",
  "error": null
}

API will return the following structure:

Parameter Type Description
status STRING Status of the response. Possible values: success or failure
fx_quote_id STRING FalconX Quote ID
client_order_id STRING Tag generated by the client for the quote/order
client_order_uuid STRING The unique identifier generated by the client to identify the quote/order
buy_price DECIMAL Buy price in quote token
sell_price DECIMAL Sell price in quote token
platform STRING Platform of the order. Possible values: api or browser
token_pair JSON Token pair for which the client placed the order (See Token Pair)
quantity_requested JSON Requested quantity (See Quantity)
side_requested STRING Side of the order. Possible values: buy or sell
t_quote STRING Order placing time in ISO 8601 date format
t_expiry STRING null
t_execute STRING Order execution time in ISO 8601 date format
is_filled BOOLEAN true if the order has been filled else false
gross_fee_bps DECIMAL Fee in basis points applicable on trade execution
gross_fee_usd DECIMAL Fee in USD notional applicable on trade execution
rebate_bps DECIMAL Rebate in basis points applicable on trade execution
rebate_usd DECIMAL Rebate in USD notional applicable on trade execution
fee_bps DECIMAL Effective Fee in basis points applicable on trade execution. Difference between gross_fee_bps and rebate_bps
fee_usd DECIMAL Effective Fee in USD notional applicable on trade execution. Difference between gross_fee_usd and rebate_usd
side_executed STRING Side of the order executed.
trader_email STRING Email of trader who placed the order
order_type STRING Order type (market or limit)
time_in_force STRING Time in force. (only present when order_type is limit)
limit_price DECIMAL Limit price of the order in quote token (only present when order_type is limit)
slippage_bps DECIMAL Acceptable slippage (in bps) on the limit_price. (only present when order_type is limit)
error JSON Error info. null if no error (see Error)

Get Order History

Get executed open, success, failure orders between the given time range. Time range should be provided in ISO 8601 date format.

HTTP Request

GET https://api.falconx.io/v1/orders

Query Parameters

Request Sample

# substitute placeholders with correct authorization header values
curl -X GET "https://api.falconx.io/v1/orders" \
      --data-urlencode "t_start=2019-06-20T00:00:00+00:00" \
      --data-urlencode "t_end=2019-06-21T00:00:00+00:00" \
      --data-urlencode "status=success" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"
Parameter Type Description
t_start STRING Start of time range in ISO 8601 date format [required]
t_end STRING End of time range in ISO 8601 date format [required]
status STRING Possible values: success, failure or open. [optional, Default value: open]
limit INTEGER Number of results per call. ( Min value: 1, Max value: 100 ) [optional, Default value: 100]
order STRING Result order by execution time. ( Possible values: asc, desc ) [optional, Default value: desc]

Response Parameters

Response Sample

[
  {
    "status": "success",
    "fx_quote_id": "00c884b056f949338788dfb59e495377",
    "client_order_id": "order-group-1",
    "client_order_uuid": "b006d50d-c1cb-4ddd-9429-782b7a4c3864",
    "buy_price": 12650,
    "sell_price": null,
    "platform": "api",
    "token_pair": {
      "base_token": "BTC",
      "quote_token": "USD"
    },
    "quantity_requested": {
      "token": "BTC",
      "value": "10"
    },
    "position_in": {
      "token" : "BTC",
      "value": 10
    },
    "position_out" : {
      "token": "USD",
      "value": 12650
    },
    "side_requested": "buy",
    "t_expiry": "2019-06-27T11:59:22.875725+00:00",
    "t_execute": "2019-06-27T11:59:22.875725+00:00",
    "t_update": "2019-06-27T11:59:22.875725+00:00",
    "is_filled": true,
    "gross_fee_bps": 8,
    "gross_fee_usd": 101.20,
    "rebate_bps": 3,
    "rebate_usd": 37.95,
    "fee_bps": 5,
    "fee_usd": 63.25,
    "side_executed": "buy",
    "order_type": "rfq",
    "error": null,
    "rejected_reason": null
  }
]

API will return a list of the following structure:

Parameter Type Description
status STRING Status of the response. (check possible values in below table)
fx_quote_id STRING FalconX Quote ID
client_order_id STRING Tag generated by the client for the quote/order
client_order_uuid STRING The unique identifier generated by the client to identify the quote/order
buy_price DECIMAL Buy price in quote token
sell_price DECIMAL Sell price in quote token
platform STRING Platform for quote. Possible values: api, browser or margin
token_pair JSON Token pair for which the client is requesting quote (See Token Pair)
quantity_requested JSON Requested quantity (See Quantity)
position_in JSON Amount to be received by the user (See Price)
position_out JSON Amount to be received by FalconX (See Price)
side_requested STRING Side of quote. Possible values: buy, sell or two_way
t_expiry STRING Quote expiry time in ISO 8601 date format
t_execute STRING Quote execution time in ISO 8601 date format
t_update STRING Quote update time in ISO 8601 date format
is_filled BOOLEAN true if quote has been executed successfully else false
gross_fee_bps DECIMAL Fee in basis points applicable on trade execution
gross_fee_usd DECIMAL Fee in USD notional applicable on trade execution
rebate_bps DECIMAL Rebate in basis points applicable on trade execution
rebate_usd DECIMAL Rebate in USD notional applicable on trade execution
fee_bps DECIMAL Effective Fee in basis points applicable on trade execution. Difference between gross_fee_bps and rebate_bps
fee_usd DECIMAL Effective Fee in USD notional applicable on trade execution. Difference between gross_fee_usd and rebate_usd
side_executed STRING Side of quote executed
order_type STRING Order type (rfq, market, limit or twap)
error JSON Error info. null if no error (see Error)
rejected_reason STRING If order rejected - reject reason else null

Possible values of status in response for request:

Request Response Possible statuses Description
open open, created, partially_filled, on_hold open: open for matching
created: created to be open for matching shortly
on_hold: on hold temporarily
partially_filled: partially filled
failure canceled, expired, rejected rejected: rejected by FalconX, canceled: canceled by user
expired: order expired before getting filled
success success, partially_filled_and_expired, partially_filled_and_canceled success: completely filled
partially_filled_and_expired: partially filled before expiring
partially_filled_and_canceled: partially filled before cancellation

Get Order Details

Get order details for a given fx_order_id.

HTTP Request

GET https://api.falconx.io/v1/orders/<fx_order_id>

Query Parameters

Request Sample

# substitute placeholders with correct authorization header values
curl -X GET "https://api.falconx.io/v1/orders/13671bce8d2a44889a5e331325d94cc8" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"

Response Parameters

Response Sample

{
    "buy_price": "1950.8349424",
    "client_order_id": "c11f57828045488080d07289974c18a5",
    "error": {
      "code": null,
      "reason": null
    },
    "fx_order_id": "13671bce8d2a44889a5e331325d94cc8",
    "limit_price": "1951",
    "order_type": "limit",
    "platform": "api",
    "position_in": {
        "token": "MKR",
        "value": "0.01"
    },
    "position_out": {
        "token": "EUR",
        "value": "1950.8349424"
    },
    "quantity_filled": {
        "token": "MKR",
        "value": "0.01"
    },
    "quantity_requested": {
        "token": "MKR",
        "value": "0.01"
    },
    "sell_price": null,
    "side": "buy",
    "slippage_bps": null,
    "status": "success",
    "t_create": "2024-07-09T07:44:10.228592+00:00",
    "t_execute": "2024-07-09T08:19:40.320900+00:00",
    "time_in_force": "gtc",
    "token_pair": {
        "base_token": "MKR",
        "quote_token": "EUR"
    },
    "fills": [
      {
        "fill_number": 1,
        "fx_quote_id": "13671bce8d2a44889a5e331325d94cc5",
        "t_fill": "2024-07-09T08:19:40.320900+00:00",
        "quantity": {
          "token": "MKR",
          "value": "0.01"
        },
        "price": {
          "token": "EUR",
          "value": "1950.8349424"
        },
        "gross_fee_bps": 0,
        "fee_bps": 0,
        "rebate_bps": 0
      }
    ]
}

API will return a list of the following structure:

Parameter Type Description
status STRING Status of the order. (check possible values in below table)
fx_order_id STRING FalconX Order ID
token_pair JSON Token pair for which the client is requesting order (See Token Pair)
quantity_requested JSON Requested quantity (See Quantity)
position_in JSON Amount to be received by the user (See Price)
position_out JSON Amount to be received by FalconX (See Price)
side STRING Side of order. Possible values: buy, sell or two_way
sell_price DECIMAL Sell price in quote token
buy_price DECIMAL Buy price in quote token
quantity_filled JSON Filled quantity (See Quantity)
t_create STRING Order create time in ISO 8601 date format
t_execute STRING Order execution time in ISO 8601 date format
t_expiry STRING Order expiry time in ISO 8601 date format
error JSON Error info. null if no error (see Error)
platform STRING Platform for order. Possible values: api, browser or margin
order_type STRING Order type (rfq, market, limit or twap)
time_in_force STRING Time in force. Possible value: fok (required only when order_type is limit)
limit_price DECIMAL Limit price of the order in the units of quote_token (required only when order_type is limit)
slippage_bps DECIMAL Slippage (in bps) on the limit_price. (This parameter is only valid when order_type is limit)
client_order_id STRING Tag generated by the client for the order
fills List[JSON] Individual fill details (see Order Fill Details)

Possible values of status in response for request:

Request Response Possible statuses Description
open open, created, partially_filled, on_hold open: open for matching
created: created to be open for matching shortly
on_hold: on hold temporarily
partially_filled: partially filled
failure canceled, expired, rejected rejected: rejected by FalconX, canceled: canceled by user
expired: order expired before getting filled
success success, partially_filled_and_expired, partially_filled_and_canceled success: completely filled
partially_filled_and_expired: partially filled before expiring
partially_filled_and_canceled: partially filled before cancellation

Get Balances

Fetches balances for all tokens.

HTTP Request

GET https://api.falconx.io/v1/balances

Query Parameters

Request Sample

# substitute placeholders with correct authorization header values
curl -X GET "https://api.falconx.io/v1/balances?platform=api" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"
Parameter Type Description
platform STRING Platform for balance. Possible values: api, browser, chat, loan, collateral, margin, equity, margin_interest or interest. If not present, cumulative balances from all platforms are returned.

Response Parameters

Response Sample

[
  {
    "token": "BTC",
    "balance": 10,
    "platform": "api"
  },
  {
    "token": "ETH",
    "balance": 100,
    "platform": "api"
  }
]

API will return a list of the following structure:

Parameter Type Description
token STRING Token symbol
balance DECIMAL Balance for that token
platform STRING Platform for balance. Possible values:api, browser, chat, loan, collateral, margin, equity, margin_interest or interest

Get Total Balances

Fetches total balances for all tokens combined over all platforms.

HTTP Request

Request Sample

# substitute placeholders with correct authorization header values
curl -X GET "https://api.falconx.io/v1/balances/total" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"

GET https://api.falconx.io/v1/balances/total

Response Parameters

Response Sample

[
  {
    "token": "BTC",
    "total_balance": 10,
  },
  {
    "token": "ETH",
    "total_balance": 100,
  }
]

API will return a list of the following structure:

Parameter Type Description
token STRING Token symbol
total_balance DECIMAL Total Balance for that token

Get Portfolio Balance Details

This endpoint retrieves all asset balances across the entire portfolio. Each item in the response represents the balance of a specific asset within a particular venue, subaccount and wallet. By default, live balances are returned. However, you can fetch snapshot balances by specifying a date and time.

HTTP Request

GET https://api.falconx.io/v1/portfolio_balance_details

Query Parameters

Request Sample

# substitute placeholders with correct authorization header values
# Example 1: Fetching Live Balances
curl -G -X GET "https://api.falconx.io/v1/portfolio_balance_details" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"

# Example 2: Fetching Snapshot Balances
curl -G -X GET "https://api.falconx.io/v1/portfolio_balance_details" \
      --data-urlencode "t_date=2024-04-02" \
      --data-urlencode "time=4pm LDN" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"
Parameter Type Description
t_date STRING [optional] Date as a string in 'yyyy-mm-dd' format for fetching a snapshot of data. For ex, 2024-04-02. If t_date is not provided, the system defaults to returning live data.
time STRING [optional] Time of snapshot. Should only be passed if a date is also passed. defaults to 0am UTC if not passed. Valid times are 0am UTC, 8am UTC, 4pm LDN and 4pm NYC

Response Parameters

Response Sample

[
  {
    "subaccount" : "main account",
    "venue" : "falconx otc",
    "wallet" : "spot",
    "asset" : "SOL",
    "net_balance" : 8.0123,
    "spot_balance" : 1.2313,
    "withdrawable" : 4.2312,
    "open_orders" : 3.5856,
    "staked" : 1.41,
    "borrowed" : -2.433,
    "interest_payable" : -0.087,
    "collateral_posted" : 1.13,
    "lent" : 2.3,
    "interest_receivable" : 0.0414,
    "collateral_received" : 4.3,
    "net_balance_usd" : 801.23,
    "spot_balance_usd" : 123.13,
    "withdrawable_usd" : 423.12,
    "open_orders_usd" : 358.56,
    "staked_usd" : 141.00,
    "borrowed_usd" : -243.30,
    "interest_payable_usd" : -8.7,
    "collateral_posted_usd" : 113.00,
    "lent_usd" : 230.00,
    "interest_receivable_usd" : 4.14,
    "collateral_received_usd" : 430.00,
    "price" : 100,
    "derivatives_mtm": 1.123,
    "derivatives_mtm_usd": 112.3
  }
]

API will return a list of the following structure:

Parameter Type Description
subaccount STRING Subaccount Name where balances are held
venue STRING Venue where Balances are held
wallet STRING Wallet Type
asset STRING Symbol of the underlying asset
net_balance DECIMAL Calculated as Assets - Liabilities where,
Assets = spot + staked + collateral_posted + lent + interest_receivable
Liabilities = borrowed+interest_payable
spot_balance DECIMAL Balance available to put on a trade including balance locked up in Open orders
withdrawable DECIMAL Balance that a client can withdraw from FalconX without liquidating their positions or cancelling open orders, capped to excess equity available in asset denomination.

Excess equity is the balance available after considering the collateral posted, exchange balances, outstanding loans etc. at the client level
open_orders DECIMAL Balance locked for pending orders
staked DECIMAL Balance staked with FalconX (Only applicable to FalconX OTC exchange)
borrowed DECIMAL Balance that customer borrowed from FalconX
interest_payable DECIMAL Interest on borrowed amount owed by the customer
collateral_posted DECIMAL Balance kept as collateral for credit availed (Only applicable to FalconX OTC exchange)
lent DECIMAL Balance lent by client to FalconX (Only applicable to FalconX OTC exchange)
interest_receivable DECIMAL Interest earned by customer on lent amount. FalconX owes this to customer (Only applicable to FalconX OTC exchange)
collateral_received DECIMAL Collateral given by FalconX to client for lent amount (Only applicable to FalconX OTC exchange)
net_balance_usd DECIMAL Net Balance in USD
spot_balance_usd DECIMAL Spot Balance in USD
withdrawable_usd DECIMAL Withdrawable Balance in USD
open_orders_usd DECIMAL Open Order Balance in USD
staked_usd DECIMAL Stake Balance in USD
borrowed_usd DECIMAL Borrowed Balance in USD
interest_payable_usd DECIMAL Interest Payable in USD
collateral_posted_usd DECIMAL Collateral Posted in USD
lent_usd DECIMAL Lent amount in USD
interest_receivable_usd DECIMAL Interest Receivable in USD
collateral_received_usd DECIMAL Collateral Received in USD
price DECIMAL Current rate of the underlying asset in USD
derivatives_mtm DECIMAL Current live MTM of the open derivatives positions
derivatives_mtm_usd DECIMAL Current live MTM in USD terms of the open derivatives positions

Get Portfolio Position Details

Get all asset Positions across the entire portfolio. Live positions are fetched if no arguments are passed and snapshot positions are fetched if a date and time are passed as arguments. Additional arguments can be passed to include or exclude derivatives and spot collateral in returned data.

HTTP Request

GET https://api.falconx.io/v1/portfolio_position_details

Query Parameters

Request Sample

# substitute placeholders with correct authorization header values
# Example 1: Fetching Live Positions with collateral included
curl -G -X GET "https://api.falconx.io/v1/portfolio_position_details" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"

# Example 2: Fetching Snapshot Positions
curl -G -X GET "https://api.falconx.io/v1/portfolio_position_details" \
      --data-urlencode "t_date=2024-04-02" \
      --data-urlencode "time=4pm LDN" \
      --data-urlencode "include_spot_collateral=False" \
      --data-urlencode "include_derivatives_collateral=True" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"
Parameter Type Description
t_date STRING [optional] Date as a string in 'yyyy-mm-dd' format for fetching a snapshot of data. For ex, 2024-04-02. If t_date is not provided, the system defaults to returning live data.
time STRING [optional] Time of snapshot. Should only be passed if a date is also passed. defaults to 0am UTC if not passed. Valid times are 0am UTC, 8am UTC, 4pm LDN and 4pm NYC
include_spot_collateral BOOLEAN [optional] Used to include or exclude spot collateral in returned data. Can be True or False. Defaults to True
include_derivatives_collateral BOOLEAN [optional] Used to include or exclude derivatives collateral in returned data. Can be True or False. Defaults to True

Response Parameters

Response Sample

# This is only a sample to showcase the response format
# Some fields may not be applicable to certain position types and will be empty
[
  {
    "subaccount": "Deribit-Account",
    "venue": "deribit",
    "wallet": "spot",
    "ticker": "SOL_USDC - 20JUN24 - $139 - C",
    "base_token": "SOL",
    "quote_token": "USDC",
    "side": "long",
    "settlement_type": "Deliverable",
    "instrument_type": "Options",
    "option_type": "call",
    "margin_type": "cross",
    "initial_margin": {"value": "0.0", "token": "SOL"},
    "maintenance_margin": {"value": "0.0", "token": "SOL"},
    "fixing_source": "deribit",
    "delta_usd": 494.05192046444,
    "delta_base": 3.60386,
    "vega": 0.3763,
    "theta": -7.5728,
    "delta_per_unit": 0.360386,
    "vega_per_unit": 0.03763,
    "theta_per_unit": -0.75728,
    "gamma_one_perc": 0.633902560096,
    "gamma_one_perc_per_unit": 0.0633902560096,
    "mark_price": {"value": "1.926066", "token": "SOL"},
    "avg_open_price": {"value": "1.5", "token": "SOL"},
    "mtm": {"value": "19.26066", "token": "SOL"},
    "mtm_usd": 2640.43721521,
    "mtm_pnl": {"value": "4.2606632060000000", "token": "SOL"},
    "mtm_pnl_usd": 584.0928447210707,
    "spot_price": 137.089654,
    "strike_price": 139,
    "estimated_liq_price": {"value": 34.334, "token": "SOL"},
    "quantity": {"value": "10.00", "token": "SOL"},
    "notional_base": 10.0,
    "notional_quote": 1370.6775934439338,
    "notional_usd": 1370.89654,
    "gross_delta_base": 3.60386,
    "gross_delta_usd": 494.05192046444,
    "gross_quantity": {"value": "10.00", "token": "SOL"},
    "gross_notional_base": 10.0,
    "gross_notional_quote": 1370.6775934439338,
    "gross_notional_usd": 1370.89654,
    "strike_notional_quote": 139,
    "strike_notional_usd": 139.022203304,
    "maturity_date": "2024-06-20 08:00:00+00:00",
    "exp_cut_time": "8am UTC",
  }
]

API will return a list of the following structure:

Parameter Type Description
subaccount STRING Subaccount Name
venue STRING Exchange
wallet STRING Wallet Type (Only applicable to spot positions)
ticker STRING Ticker of this position
base_token STRING Base Token
quote_token STRING Quote Token
side STRING Side, can be short or long
settlement_type STRING Settlement Type of this positions (only applicable to FalconX OTC positions)
instrument_type STRING Instrument or position type. Can be spot, options, futures or forwards
option_type STRING Option Type, can be call or put (only applicable to options positions)
margin_type STRING Margin Type
initial_margin JSON Initial Margin (See Quantity)
maintenance_margin JSON Maintenance Margin (See Quantity)
fixing_source STRING Fixing Source
delta_usd DECIMAL Position Delta in USD
delta_base DECIMAL Position Delta in base token terms
vega DECIMAL Vega in quote token terms
theta DECIMAL Theta in quote token terms
delta_per_unit DECIMAL Unit Delta
vega_per_unit DECIMAL Unit Vega
theta_per_unit DECIMAL Unit Theta
gamma_one_perc DECIMAL Gamma 1% in quote token terms
gamma_one_perc_per_unit DECIMAL Unit Gamma 1%
mark_price JSON Mark Price (See Quantity)
avg_open_price JSON Average Open Price (See Quantity)
mtm JSON Marked to Market (Market Value) (See Quantity)
mtm_usd DECIMAL MTM in USD
mtm_pnl JSON MTM PNL (See Quantity)
mtm_pnl_usd DECIMAL MTM PNL in USD
spot_price DECIMAL Spot Price
spot_price_change DECIMAL Change in spot price since 12 AM UTC (Only applicable to live data)
strike_price DECIMAL Strike Price, if applicable
estimated_liq_price JSON Estimated Liquidation Price (See Quantity)
quantity JSON Quantity of position (See Quantity)
notional_base DECIMAL Notional in base token terms
notional_quote DECIMAL Notional in quote token terms
notional_usd DECIMAL Notional in USD
gross_delta_base DECIMAL Absolute value of Position Delta in base token terms
gross_delta_usd DECIMAL Absolute value of Position Delta in USD
gross_quantity JSON Absolute value of Quantity of position (See Quantity)
gross_notional_base DECIMAL Absolute value of Notional in base token terms
gross_notional_quote DECIMAL Absolute value of Notional in quote token terms
gross_notional_usd DECIMAL Absolute value of Notional in USD
strike_notional_quote DECIMAL Notional Strike in quote token terms
strike_notional_usd DECIMAL Notional Strike in USD
maturity_date STRING Maturity Date, if applicable
exp_cut_time STRING Expiry Cutoff Time

Get Portfolio Position Summary

Get a summary of aggregated numbers like notional and delta over all the positions across the entire portfolio. Summary for live positions is fetched if no date and time arguments are passed and snapshot positions are fetched if a date and time is passed as arguments. Additional arguments can be passed to include or exclude derivatives and spot collateral in returned data. Details of underlying positions can also be fetched by passing an appropriate argument.

HTTP Request

GET https://api.falconx.io/v1/portfolio_position_summary

Query Parameters

Request Sample

# substitute placeholders with correct authorization header values
# Example 1: Fetching Live Positions with collateral included
curl -G -X GET "https://api.falconx.io/v1/portfolio_position_summary" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"

# Example 2: Fetching Snapshot Positions
curl -G -X GET "https://api.falconx.io/v1/portfolio_position_details" \
      --data-urlencode "t_date=2024-04-02" \
      --data-urlencode "time=4pm LDN" \
      --data-urlencode "include_spot_collateral=False" \
      --data-urlencode "include_derivatives_collateral=True" \
      --data-urlencode "include_details=False" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"
Parameter Type Description
t_date STRING [optional] Date as a string in 'yyyy-mm-dd' format for fetching a snapshot of data. For ex, 2024-04-02. If t_date is not provided, the system defaults to returning live data.
time STRING [optional] Time of snapshot. Should only be passed if a date is also passed. defaults to 0am UTC if not passed. Valid times are 0am UTC, 8am UTC, 4pm LDN and 4pm NYC
include_spot_collateral BOOLEAN [optional] Used to include or exclude spot collateral in returned data. Can be True or False. Defaults to True
include_derivatives_collateral BOOLEAN [optional] Used to include or exclude derivatives collateral in returned data. Can be True or False. Defaults to True
include_details BOOLEAN [optional] If True, the underyling position details (as returned by Position Details api) are also included in the returned data. Can be True or False. Defaults to False

Response Parameters

Response Sample

# This is only a sample to showcase the response format
# Some fields may not be applicable to certain position types and will be empty
{
  "positions_overview":{
    "net_balance": 14488664795.404743,
    "net_balance_long": 1331343.699301274,
    "net_balance_short": -14487333451.705442,
    "notional_net": 14488666978.115553,
    "notional_long": 1333526.4101117256,
    "notional_short": -14487333451.705442,
    "notional_gross": 20014928373.012516,
    "notional_net_percent": 72.38930216533576,
    "notional_long_percent": 0.006662658917679714,
    "notional_short_percent": 72.38263950641809,
    "notional_gross_percent": 100,
    "delta_net": 14164944620.39119,
    "delta_long": 1297036.5570548149,
    "delta_short": -14163647583.834133,
    "delta_gross": 19691205350.840836,
    "delta_net_percent": 97.76570043144193,
    "delta_long_percent": 0.008952077885508027,
    "delta_short_percent": -97.75674835355642,
    "delta_gross_percent": 135.90766042904204
  },
  "positions_details": [
    {
      "subaccount": "Deribit-Account",
      "venue": "deribit",
      "wallet": "spot",
      "ticker": "SOL_USDC - 20JUN24 - $139 - C",
      "base_token": "SOL",
      "quote_token": "USDC",
      "side": "long",
      "settlement_type": "Deliverable",
      "instrument_type": "Options",
      "option_type": "call",
      "margin_type": "cross",
      "initial_margin": {"value": "0.0", "token": "SOL"},
      "maintenance_margin": {"value": "0.0", "token": "SOL"},
      "fixing_source": "deribit",
      "delta_usd": 494.05192046444,
      "delta_base": 3.60386,
      "vega": 0.3763,
      "theta": -7.5728,
      "delta_per_unit": 0.360386,
      "vega_per_unit": 0.03763,
      "theta_per_unit": -0.75728,
      "gamma_one_perc": 0.633902560096,
      "gamma_one_perc_per_unit": 0.0633902560096,
      "mark_price": {"value": "1.926066", "token": "SOL"},
      "avg_open_price": {"value": "1.5", "token": "SOL"},
      "mtm": {"value": "19.26066", "token": "SOL"},
      "mtm_usd": 2640.43721521,
      "mtm_pnl": {"value": "4.2606632060000000", "token": "SOL"},
      "mtm_pnl_usd": 584.0928447210707,
      "spot_price": 137.089654,
      "strike_price": 139,
      "estimated_liq_price": {"value": 34.334, "token": "SOL"},
      "quantity": {"value": "10.00", "token": "SOL"},
      "notional_base": 10.0,
      "notional_quote": 1370.6775934439338,
      "notional_usd": 1370.89654,
      "gross_delta_base": 3.60386,
      "gross_delta_usd": 494.05192046444,
      "gross_quantity": {"value": "10.00", "token": "SOL"},
      "gross_notional_base": 10.0,
      "gross_notional_quote": 1370.6775934439338,
      "gross_notional_usd": 1370.89654,
      "strike_notional_quote": 139,
      "strike_notional_usd": 139.022203304,
      "maturity_date": "2024-06-20 08:00:00+00:00",
      "exp_cut_time": "8am UTC",
    }
  ]
}

API will return a JSON with following fields:

Parameter Type Description
positions_overview JSON A JSON containing aggregated notional, balance and delta numbers. JSON struct is defined in next table
position_details LIST Only returned if include_details param is sent as True. This is same as the response of Position Details api

The overview JSON will have the following fields:

Parameter Type Description
net_balance DECIMAL Net balance of the portfolio in USD
net_balance_long DECIMAL Net balance of long positions across the portfolio in USD
net_balance_short DECIMAL Net balance of short positions across the portfolio in USD
notional_net DECIMAL Sum of notional of all positions in USD
notional_long DECIMAL Sum of notional of all long positions in USD
notional_short DECIMAL Sum of notional of all short positions in USD
notional_gross DECIMAL Sum of absolute value of notional of all positions in USD
notional_net_percent DECIMAL 100 * (notional_net / notional_gross)
notional_long_percent DECIMAL 100 * (notional_long / notional_gross)
notional_short_percent DECIMAL 100 * (notional_short / notional_gross)
notional_gross_percent DECIMAL Value is always 100
delta_net DECIMAL Sum of delta of all positions in USD
delta_long DECIMAL Sum of delta of all long positions in USD
delta_short DECIMAL Sum of delta of all short positions in USD
delta_gross DECIMAL Sum of absolute value of delta of all positions in USD
delta_net_percent DECIMAL 100 * (delta_net / net_balance)
delta_long_percent DECIMAL 100 * (delta_long / net_balance)
delta_short_percent DECIMAL 100 * (delta_short / net_balance)
delta_gross_percent DECIMAL 100 * (delta_gross / net_balance)

Get Equity Summary

Fetches equity summary of customer.

HTTP Request

GET https://api.falconx.io/v1/equity/summary

Request Sample

# substitute placeholders with correct authorization header values
curl -X GET "https://api.falconx.io/v1/equity/summary" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"

Response Parameters

Response Sample

{
  "user_id" :   781,
  "account_id"  :   null,
  "customer_id" :   75,
  "credit_left" :   84316360.88999999,
  "credit_limit"    :   100000000,
  "equity"  :   4436239.02,
  "negative_equity" :   -15683639.11
}

API will return a list of the following structure:

Parameter Type Description
user_id STRING Unique user identifier
account_id STRING Unique account identifier
customer_id STRING Unique customer identifier
credit_limit DECIMAL Credit limit of customer
credit_left DECIMAL Credit remaining
equity DECIMAL Customer's equity value
negative_equity DECIMAL Customer's negative equity value

Get Transfer

Get deposit / withdrawal by fx_transfer_id or client_reference_id.

HTTP Request

GET https://api.falconx.io/v1/transfer

Query Parameters

Request Sample

# substitute placeholders with correct authorization header values
curl -X GET "https://api.falconx.io/v1/transfer" \
      --data-urlencode "client_reference_id=b006d50d-c1cb-4ddd-9429-782b7a4c3864" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"
Parameter Type Description
client_reference_id STRING [optional] The unique identifier generated by the client to identify the withdrawal request.
fx_transfer_id STRING [optional] The unique identifier generated by the falconx to identify the withdrawal request.

Response Parameters

Response Sample

[
  {
    "type": "deposit",
    "platform": "browser",
    "token": "BTC",
    "quantity": 1.0,
    "status": "completed",
    "t_create": "2019-06-20T01:01:01+00:00",
    "fx_transfer_id": "00c884b056f949338788dfb59e495377",
    "transaction_hash": "9032ala8lkj849ku882bvb23847x0fdh03yb"
  }
]

API will return a list of the following structure:

Parameter Type Description
type STRING Type of transfer. Possible values: deposit or withdrawal
platform STRING Platform for transfer. Possible values: `api, browser, chat, loan, collateral, margin, equity, or margin_interest
token DECIMAL Token symbol
quantity DECIMAL Quantity
status STRING Status of the transfer. Possible values: requested, processing, pending, mined, completed, cancelled or failed
t_create JSON Time of creation
client_reference_id STRING The unique identifier generated by the client to identify the withdrawal request.
fx_transfer_id STRING The unique identifier generated by the falconx to identify the withdrawal request.
transaction_hash STRING The unique hash generated for the on-chain transfer.

Get Transfers

Get deposits / withdrawals between the given time range. Time range should be provided in ISO 8601 date format.

HTTP Request

GET https://api.falconx.io/v1/transfers

Query Parameters

Request Sample

# substitute placeholders with correct authorization header values
curl -X GET "https://api.falconx.io/v1/transfers" \
      --data-urlencode "t_start=2019-06-20T00:00:00+00:00" \
      --data-urlencode "t_end=2019-06-21T00:00:00+00:00" \
      --data-urlencode "platform=api" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"
Parameter Type Description
t_start STRING Start of time range in ISO 8601 date format
t_end STRING End of time range in ISO 8601 date format
platform STRING Platform for transfer. Possible values: api, browser, chat, loan, collateral, margin, equity, or margin_interest. If not present transfers from all platforms are returned

Response Parameters

Response Sample

[
  {
    "fx_transfer_id": "00c884b056f949338788dfb59e495377",
    "transaction_hash": "9032ala8lkj849ku882bvb23847x0fdh03yb",
    "type": "deposit",
    "platform": "browser",
    "token": "BTC",
    "quantity": 1.0,
    "status": "completed",
    "t_create": "2019-06-20T01:01:01+00:00"
  }
]

API will return a list of the following structure:

Parameter Type Description
fx_transfer_id STRING Falconx Transfer ID (Unique identifier for transfer)
transaction_hash STRING The unique hash generated for the on-chain transfer.
type STRING Type of transfer. Possible values: deposit or withdrawal
platform STRING Platform for transfer. Possible values: `api, browser, chat, loan, collateral, margin, equity, or margin_interest
token DECIMAL Token symbol
quantity DECIMAL Quantity
status STRING Status of the transfer. Possible values: requested, processing, pending, mined, completed, cancelled or failed
t_create JSON Time of creation

Get 30-day Trailing Volume

Get trading volume for the last 30 days.

HTTP Request

GET https://api.falconx.io/v1/get_30_day_trailing_volume

Request Sample

# substitute placeholders with correct authorization header values
curl -X GET "https://api.falconx.io/v1/get_30_day_trailing_volume" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"

Response Parameters

Response Sample

{
  "end_date": "2019-11-18T06:54:27.623978+00:00",
  "start_date": "2019-10-19T06:54:27.623978+00.00",
  "usd_volume": 69100283.78000,
}

API will return a list of the following structure:

Parameter Type Description
end_date STRING End date of the resultant volume
start_date STRING Start date of the resultant volume
usd_volume DECIMAL Total volume traded in USD between start_date and end_date

Get Trade Volume

Get trading volume between the given time range. Time range should be provided in ISO 8601 date format.

HTTP Request

GET https://api.falconx.io/v1/get_trade_volume

Query Parameters

Request Sample

# substitute placeholders with correct authorization header values
curl -X GET "https://api.falconx.io/v1/get_trade_volume" \
      --data-urlencode "t_start=2019-06-20T00:00:00+00:00" \
      --data-urlencode "t_end=2019-06-21T00:00:00+00:00" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"
Parameter Type Description
t_start STRING Start of time range in ISO 8601 date format
t_end STRING End of time range in ISO 8601 date format

Response Parameters

Response Sample

{
  "end_date": "2019-11-18T06:54:27.623978+00:00",
  "start_date": "2019-10-19T06:54:27.623978+00.00",
  "usd_volume": 69100283.78000,
}

API will return a list of the following structure:

Parameter Type Description
end_date STRING End date of the resultant volume
start_date STRING Start date of the resultant volume
usd_volume DECIMAL Total volume traded in USD between start_date and end_date

Get Trade Limits

Get trade limits.

Please note that user entering limit orders will be allowed to enter limit orders representing transactions of two times their net limit. In example, if the user's net limit is $500,000, users may enter in limit orders representing $500,000 worth of buy limit orders and $500,000 worth of sell limit orders for a total outstanding amount of $1,000,000 in open orders.

Any limit orders that are attempted to be placed, but would violate the net limit on either the buy side of the sell side will be rejected upon entry attempt.

HTTP Request

GET https://api.falconx.io/v1/get_trade_limits

Query Parameters

Request Sample

# substitute placeholders with correct authorization header values
curl -X GET "https://api.falconx.io/v1/get_trade_limits?platform=api" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"
Parameter Type Description
platform STRING Platform to withdraw from. Possible values: api, browser, equity

Response Parameters

Response Sample

{
  "gross_limits": {
    "available": 99774.78,
    "total": 1000000,
    "used": 900225.22
  },
  "net_limits": {
    "available": 81711.78,
    "total": 1000000,
    "used": 918288.22
  }
}
Parameter Type Description
gross_limits JSON Gross Limits (see Trade Limits)
net_limits JSON Net Limits (see Trade Limits)

Get Token Balance info

Get balance and withdrawal info given token

HTTP Request

GET https://api.falconx.io/v1/get_token_balance_info

Query Parameters

Request Sample

# substitute placeholders with correct authorization header values
curl -X GET "https://api.falconx.io/v1/get_token_balance_info?token=BTC" \
      -H "FX-ACCESS-SIGN: <signature>" \
      -H "FX-ACCESS-TIMESTAMP: <timestamp>" \
      -H "FX-ACCESS-KEY: <api_key>" \
      -H "FX-ACCESS-PASSPHRASE: <passphrase>" \
      -H "Content-Type: application/json"
Parameter Type Description
token STRING Token for which balance info is needed . Example values: BTC, ETH

Response Parameters

Response Sample

{
    "token": "BTC",
    "token_balance": {
        "token": "BTC",
        "value": "1.20021231"
    },
    "locked_balance": {
        "token": "BTC",
        "value": "0.011"
    },
    "token_withdraw_limit": {
        "token": "BTC",
        "value": "1.18921231"
    },
}
Parameter Type Description
token STRING The token for which data hs been requested
token_balance JSON Token pair of current balance (See Token Pair)
locked_balance JSON Token pair of locked balance in open orders (See Token Pair)
token_withdraw_limit JSON Token pair of max withdrawable limit (See Token Pair)

Request Withdrawal

Submit a request for withdrawal.

HTTP Request

POST https://api.falconx.io/v1/submit_withdrawal_request

Query Parameters

Request Sample

{
  "token": "BTC",
  "amount": "1",
  "platform": "browser",
  "label": "default"    // optional
}

Response Sample

# success response
{
    "message": "Withdrawal request submitted successfully",
    "status": "success"
}


# failure response when requested withdrawal amount is more than the current balance
{
    "error": {
        "code": "INSUFFICIENT_BALANCE_TO_WITHDRAW",
        "reason": "Withdrawal balance should be less that or equal to the balance in account."
    },
    "status": "failure"
}
Parameter Type Description
token STRING Token to withdraw. E.g. BTC, ETH.
amount DECIMAL Quantity of token to withdraw.
platform STRING Platform to withdraw from. Possible values: api, browser, equity.
label STRING [Optional] Label to identify the withdrawal address. [Compulsory] Only if you have multiple addresses for the token

Request Withdrawal (with ref ID)

Submit a request for withdrawal.

HTTP Request

POST https://api.falconx.io/v1/withdraw

Query Parameters

Request Sample

{
  "token": "BTC",
  "amount": "1",
  "platform": "browser",
  "client_reference_id": "b006d50d-c1cb-4ddd-9429-782b7a4c3864", // optional
  "label": "default"    // optional
}

Response Sample

# success response
{
    "message": "Withdrawal request submitted successfully",
    "status": "success",
    "fx_transfer_id": "13671bce8d2a44889a5e331325d94cc8",
    "client_reference_id": "b006d50d-c1cb-4ddd-9429-782b7a4c3864"
}


# failure response when requested withdrawal amount is more than the current balance
{
    "error": {
        "code": "INSUFFICIENT_BALANCE_TO_WITHDRAW",
        "reason": "Withdrawal balance should be less that or equal to the balance in account."
    },
    "status": "failure"
}
Parameter Type Description
token STRING Token to withdraw. E.g. BTC, ETH.
amount DECIMAL Quantity of token to withdraw.
platform STRING Platform to withdraw from. Possible values: api, browser, equity.
client_reference_id STRING [optional] The unique identifier generated by the client to identify the withdrawal request.
label STRING [Optional] Label to identify the withdrawal address. [Compulsory] Only if you have multiple addresses for the token

Get Derivatives

Fetches information about all derivative trades and marks.

HTTP Request

GET https://api.falconx.io/v1/derivatives

Query Parameters

Request Sample

{
  "trade_status": "open",
  "product_type": "option",
  "market_list": "BTC-USD,ETH-USD"
}
Parameter Type Description
trade_status STRING Filter by statuses open, terminated, settled, defaulted. If not present, all are returned.
product_type STRING Filter by types ndf, option, call_option, put_option, irs. If not present, all are returned.
market_list STRING Comma separated list of base token / quote token markets to filter trades, e.g. "BTC-USD,ETH-USD".

Response Parameters

Response Sample

[
  {
    "counterparty_margin_percent": {
      "value": 15.0,
      "token": "USD"
    }
    "daily_mark": {
      "value": -2.0,
      "token": "USD"
    },
    "delta": -262.0,
    "effective_date": null,
    "fixing_expiry_time": "4pm NYC",
    "maturity_date": "2022-02-26T00:00:00+00:00",
    "premium": {
      "token": "USD",
      "value": 100000.00
    },
    "option_type": "put",
    "product": "option",
    "quantity": 100.0,
    "side": "sell",
    "status": "open",
    "spot_reference_price": {
    "token": "USD",
    "value": 20010.0
    }
    "strike_price": {
      "token": "USD",
      "value": 20000.0
    },
    "token_pair": {
      "base_token": "BTC",
      "quote_token": "ETH"
    },
    "trade_date": "2022-02-26T00:03:00+00:00",
    "trade_id": "13db3a3f832e444a90435e900d1c3222",
    "trade_notional": {
      "token": "USD",
      "value": 2001000.0
    },
    "trader": "[email protected]",
    "trading_entity": "solios",
    "vega": {
      "value": -272.0
      "token": "USD"
    }
  }
]
Parameter Type Description
counterparty_margin_percent JSON Counterparty margin percent (See Quantity)
daily_mark JSON Daily mark of trade (See Quantity), expressed from client perspective.
delta DECIMAL Delta of trade, expressed from client perspective.
effective_date STRING ISO 8601 date format.
fixing_expiry_time STRING Possible values: 3am UTC, 8am UTC, 4pm UTC, 4pm London, 4pm NYC, 5pm NYC, 7pm NYC
maturity_date STRING ISO 8601 date format.
option_type STRING Type of option if applicable call, put, null if not option.
premium JSON Premium of trade (See Quantity)
product STRING Type of instrument, e.g. option, ndf, irs
quantity DECIMAL Quantity of base token.
side STRING Side of the order. Possible values: buy or sell
spot_reference_price JSON Spot reference price (See Price)
status STRING Trade status Possible values: open, terminated, settled, defaulted
strike_price JSON Strike price (See Price)
token_pair JSON Base token and quote token (see Token Pair)
trade_date STRING ISO 8601 date format.
trade_id STRING Unique id of trade.
trade_notional JSON Notional amount of trade (See Quantity)
trader STRING Email of trader
trading_entity STRING Legal entity of trade
vega JSON Vega of trade (See Quantity), expressed from client perspective.

Get Derivatives Margin

Fetches total margin for derivatives.

HTTP Request

GET https://api.falconx.io/v1/derivatives/margin

Response Parameters

Response Sample

[
  {
    "token": "BTC",
    "total_margin": 400.4
  },
  {
    "token": "ETH",
    "total_margin": 130000.5
  }
  {
    "token": "USD",
    "total_margin": 1333033.02
  }
]
Parameter Type Description
token STRING Ticker symbol of currency.
total_margin DECIMAL Total quantity of currency.

Get Derivatives Positions

Fetches a list of derivatives positions.

HTTP Request

GET https://api.falconx.io/v1/derivatives/option/positions

GET https://api.falconx.io/v1/derivatives/forward/positions

Response Parameters

Response Sample

# Sample response for option positions
[
  {
    "base_asset": "BTC",
    "quote_asset": "USD",
    "contract_name": "BTC-USD-29SEP23-20000-C-8UTC-ND-USD",
    "fixing_source": "deribit",
    "settlement_type": "Non-Deliverable (USD)",
    "instrument_type": "call",
    "maturity_date_time": "2023-09-29T08:00:00+00:00",
    "strike_price": 20000.0,
    "signed_quantity": -300.0,
    "average_open_price": 1.30,
    "mark_price": 0.80
    "current_cost": -390.0,
    "current_market_value": -240.0,
    "unrealized_pnl": 150.0,
    "quantity_delta": 50.0,
    "quantity_vega": 60.0,
    "quantity_theta": 70.0,
    "multiplier": 1.0,
    "position_id": "OPT-d84a37a3472f4e1a81085e5f2147e7d2",
  }
]

# Sample response for forward positions
[
  {
    "base_asset": "BTC",
    "quote_asset": "USD",
    "contract_name": "BTC-USD-28SEP23-8UTC-ND-USD",
    "fixing_source": "binance_perps",
    "settlement_type": "Non-Deliverable (USD)",
    "instrument_type": "forward",
    "maturity_date_time": "2023-09-28T08:00:00+00:00",
    "signed_quantity": 20.0,
    "average_open_price": 42000.0,
    "mark_price": 41500.0
    "current_cost": 840000.0,
    "current_market_value": 830000.0,
    "unrealized_pnl": -10000.0,
    "multiplier": 1.0,
    "position_id": "FWD-1a81085e5f2147e7d2d84a37a3472f4e",
  }
]
Parameter Type Description
base_asset STRING Base currency for the position.
quote_asset STRING Quote currency for the position.
contract_name STRING Ticker for the contract associated with the position. The format is [Base Currency]-[Quote Currency]-[Maturity Date]-[Strike Price]-[Option Type]-[Fixing Time]-[Settlement Type]
fixing_source STRING Settlement price source for the contract.
settlement_type STRING Deliverable or non-deliverable and settlement currency for the contract.
instrument_type STRING Option type ("call" or "put") or "forward".
maturity_date_time STRING Maturity date/time in ISO 8601 format.
strike_price DECIMAL Strike price for the contract associated with the position. (This field is only for options.)
signed_quantity DECIMAL Total quantity for the position. Positive quantity corresponds to buying; negative quantity corresponds to selling.
average_open_price DECIMAL Weighed average price of open trades for the position.
mark_price DECIMAL Latest per-unit mark price for the position.
current_cost DECIMAL Total open premium amount (for options) or forward price (for forwards) for the position.
current_market_value DECIMAL Latest market value (per-unit mark price multiplied by quantity) for the position.
unrealized_pnl DECIMAL Latest unrealized mark-to-market PnL for the position.
quantity_delta DECIMAL Latest quantity delta (per-unit delta multiplied by signed quantity) for the position. (This field is only for options.)
quantity_vega DECIMAL Latest quantity vega (per-unit vega multiplied by signed quantity) for the position. (This field is only for options.)
quantity_theta DECIMAL Latest quantity theta (per-unit theta multiplied by signed quantity) for the position. (This field is only for options.)
multiplier DECIMAL Multiplier is always 1. Each contract has only 1 base asset as the underlying asset.
position_id STRING Internal ID for the position.

Get Derivatives Transactions

Fetches a list of derivatives transactions for a trade.

HTTP Request

GET https://api.falconx.io/v1/derivatives/<trade_id>/transactions

Response Parameters

Response Sample

# Sample response for option trade
[
  {
    "premium_per_unit": 49.7300000000000000,
    "side": "sell",
    "signed_quantity": -15.0000000000000000,
    "trade_effect": "open",
    "transaction_date": "2022-08-29T15:47:00+00:00",
    "transaction_id": "OPT-ad9e7dc1422b4c9fa18f1baf205b487f",
    "transaction_type": "opened",
    "novated": false,
    "settlement_price": 45123.0000000000000000,
  }
]

# Sample response for forward trade
[
  {
    "forward_price": 48760.0000000000000000,
    "side": "buy",
    "signed_quantity": 12.0000000000000000,
    "trade_effect": "close",
    "transaction_date": "2022-08-27T15:47:00+00:00",
    "transaction_id": "FWD-9fa18f1baf205b487fad9e7dc1422b4c",
    "transaction_type": "settled",
    "novated": false,
    "settlement_price": 48760.0000000000000000,
  }
]
Parameter Type Description
premium_per_unit DECIMAL The premium/settlement amount/termination charges per unit for the transaction. (This field is only for options.)
forward_price DECIMAL The price of the forward transaction. (This field is only for forwards.)
side STRING Side of the transaction. Possible values: buy or sell
signed_quantity DECIMAL The quantity of the transaction. Positive quantity corresponds to buying; negative quantity corresponds to selling.
trade_effect STRING The effect of the transaction on the trade. Possible values: open or close
transaction_date STRING Timestamp of the transaction, in ISO 8601 format.
transaction_id STRING Internal ID of the transaction.
transaction_type STRING Type of the transaction. Possible values: opened, partially_terminated, expired, exercised, terminated, settled
novated BOOLEAN Whether the transaction was part of a novation.
settlement_price DECIMAL or NULL For an exercise/expire option transaction or a settled forward transaction, the settlement price at the expiry cut time. For all other transactions, this value is null.

Customer Trading Limits

Rate Limits

Response Sample

{
  "num_quotes_limit": {
    "per_hour": 60,
    "per_minute": 24,
    "per_second": 5
  }
}

Rate limit for quoting will be returned in the following format:

Parameter Type Description
per_hour INTEGER Limit on no. of quote requests per hour
per_minute INTEGER Limit on no. of quote requests per minute
per_second INTEGER Limit on no. of quote requests per second

HTTP Request at : GET https://api.falconx.io/v1/rate_limit

Trade Size Limits

Response Sample

[
  {
    "platform": "browser",
    "token_pair": {
      "base_token": "BTC",
      "quote_token": "USD"
    },
    "trade_size_limits_in_quote_token": {
      "max": 500000.00,
      "min": 4000.00
    }
  },
  {
    "platform": "api",
    "token_pair": {
      "base_token": "ETH",
      "quote_token": "USD"
    },
    "trade_size_limits_in_quote_token": {
      "max": 500000.00,
      "min": 1000.00
    }
  }
]

The API will return the minimum and maximum trade size for a token pair in the following format:

Parameter Type Description
platform STRING Trading Platform (API or Browser)
base_token STRING Base Token
quote_token STRING Quote Token
min DECIMAL Minimum allowed trade size in terms of quote token
max DECIMAL Maximum allowed trade size in terms of quote token

HTTP Request at : GET https://api.falconx.io/v1/trade_sizes

FIX API docs

Fix Api Docs is available here FIX-Document.pdf

Websocket Prices

This section outlines the functionality of the Falconx Plain WebSocket API's. In order to access this functionality, each firm must have a set of API keys generated that has trading access enabled. For users that would like to access the FalconX API but do not yet have a set of API keys generated, please reach out to your FalconX Customer Rep or inquire on chat.

You can check out our sample websocket clients here: https://github.com/falconxio/fx-ws-clients

In order to successfully stream market data over a websocket connection. The following below mentioned steps need to be performed.

  1. Connect to the websocket server.
  2. Send an Auth message and authenticate the connection.
  3. Send a subscription message to the required market/symbol.

Creating a connection

Open a websocket connection to wss://stream.falconx.io/price.tickers

via the websocket connect action.

# websocket-client==1.6.4
from websocket import create_connection, WebSocketApp
def on_message(ws, message):
    print(message)
def on_error(ws, error):
    print("Error : ", error)
def on_close(ws, close_status_code, close_msg):
    print("### closed ###")
def on_open(ws):
    print("Opened connection")
# For Long-lived Connection client 
conn = WebSocketApp("wss://stream.falconx.io/price.tickers",
                        on_open=on_open,
                        on_message=on_message,
                        on_error=on_error,
                        on_close=on_close)
conn.run_forever(reconnect=5)
# Or alternatively Short lived Connection client
ws = create_connection("wss://stream.falconx.io/price.tickers")
ws.send("Hello, World")
result =  ws.recv()
print("Received '%s'" % result)
ws.close()

Send Authentication message

The authentication message action=auth must contain the user identification credentials (api_key and passphrase) along with a signed message and current timestamp.

Sample Request:

// Sample Request
{
    "action": "auth",
    "api_key": "xxyyzz",
    "passphrase": "aabbcc",
    "signature": "xt64fsrt18_uid",
    "timestamp": "16524352778",
    "request_id": "my_sample_request"
}

Sample Response:

// Sample Response
{
    "event": "auth_response",
    "status": "success",
    "request_id": "my_sample_request",
    "body": {
        "message": "Authentication successful",
        "session_id": "a1b2c3d4e5f6g7h8i9j10k11lm"
    }
}

Please Note: A successful auth response will contain the 26 character sessionId.

Signing the Authentication message

The signature field is generated by creating a sha256 HMAC using the base64-decoded secret key on the prehash string timestamp + method + requestPath (where + represents string concatenation) and base64-encode the output. The timestamp value is the same as the FX-ACCESS-TIMESTAMP header.

The method should be UPPER CASE. While creating a websocket connection, method would always be GET, and the requestPath would always be /price.tickers.

Remember to first base64-decode the alphanumeric secret string before using it as the key for HMAC. Also, base64-encode the digest output before sending in the header.

import base64
import hashlib
import hmac
import time
import json

secret = "secret"

def get_signature(self, timestamp, path):
    method = "GET"
    message = "".join([timestamp, method, path, ""])
    hmac_key = base64.b64decode(secret)
    signature = hmac.new(hmac_key, message.encode(), hashlib.sha256)
    signature_b64 = base64.b64encode(signature.digest())
    signature = signature_b64.decode("utf-8")
    return signature

timestamp = int(time.time())
signature = get_signature(str(timestamp), "/price.tickers")

req = {
  "action":      "auth",
  "api_key":     "api_key",
  "passphrase":  "passphrase",
  "signature":   signature,
  "timestamp":   timestamp,
  "request_id":  "my_request"
}

conn.send(data=json.dumps(req))

Send subscription message

Subscription requests are required to be sent in order to receive periodic price ticks for the requested market and levels.

Users can request multiple levels of the same market / symbol in the same request. (in such a case response will have price for all the requested levels as a list)

Subscription Message Structure:

// Subscription Message
{
    "base_token": "ETH",
    "quote_token": "USD",
    "quantity": {
        "token": "ETH",
        "levels": [0.1, 1]
    },
    "request_id": "my_request_1",
    "action": "subscribe"
}

Subscription Successful Response

// Subscription Successful Response
{
    "event": "subscribe_response",
    "request_id": "my_request_1",
    "status": "success",
    "body": {
        "message": "Subscription successful"
    }
}

Upon successful subscription. A continuous price streams would begin.

** As this is a very rapid stream, users need to make sure the client is processing these streams fast enough so the network layer is not clogged up

See the sample Stream response in next section

Reading a Market Data Stream

A Market Data Stream will look like below.

sample market data stream

{
  "event": "stream",
  "request_id": "my_request_1",
  "status": "success",
  "body": [
    {
      "base_token": "ETH",
      "buy_price": 1641.28732689,
      "quantity": 0.1,
      "quantity_token": "ETH",
      "quote_token": "USD",
      "sell_price": 1622.96733067,
      "t_create": 1696805849736
    },
    {
      "base_token": "ETH",
      "buy_price": 1641.23732689,
      "quantity": 1,
      "quantity_token": "ETH",
      "quote_token": "USD",
      "sell_price": 1622.97733067,
      "t_create": 1696805849736
    }
  ]
}

The market data will be part of the body of the response.

The body is a list of market data messages for all the levels subscribed in the current connection for a given market/symbol/token.

base_token :

Base token of the requested market/symbol/token. This field cannot be null and will always have a valid value.

Eg: ETH in ETH/USD market

quote_token:

Quote token of the requested market/symbol/token. This field cannot be null and will always have a valid value.

Eg: USD in ETH/USD market

quantity:

The particular level / quantity in terms of quantity_token of the MD message. This field cannot be null and will always have a valid value.

quantity_token:

Refers the the unit token for quantity. This field cannot be null and will always have a valid value.

t_create:

The price creation timestamp from server. This can be used to validate the creation of the price on server side and hence can be analysed to check for message delays. This field cannot be null and will always have a valid value.

buy_price:

Buy price for the given market and quantity. This field can be null if there is no buy side price for the given market/symbol/token and quantity.

sell_price:

Sell price for the given market and quantity. This field can be null if there is no sell side price for the given market/symbol/token and quantity.

Please Note: In case there are no valid prices for any requested market/symbol/token and quantity at any given point in time. The client will still receive Market Data (stream) messages but with empty/null buy/sell price.

Send Unsubscription message

An already subscribed market can be unsubscribed to stop any further streams.

Unsubscribe Message Structure:

// Unsubscribe Message
{
    "base_token": "ETH",
    "quote_token": "USD",
    "request_id": "my_request_1",
    "action": "unsubscribe"
}

Unsubscribe Successful Response

// Unsubscribe Successful Response
{
    "event": "unsubscribe_response",
    "request_id": "my_request_1",
    "status": "success",
    "body": {
        "message": "UnSubscription successful"
    }
}

Data Requests

Clients can request connection config data via data_request messages.

request_type can be one of max_levels allowed_markets max_connections .

Sample data request

// Sample data request
{
    "action": "data_request",
    "request_id": "my_request_1",
    "request_type": "max_levels"
}

Sample Data response

// Sample Data response
{
    "event": "data_response",
    "request_id": "my_request_1",
    "status": "success",
    "body": {
      "max_levels": 6
    }
}

Connection Requirements

Heartbeats

The server will send a PING (control message) periodically every 30 seconds (PING_INTERVAL). The client will be expected to send a response (PONG control message) back to the server.

This PING - PONG communication is a successful heartbeat.

The client will be required to send the PONG response within 25 seconds (PING_TIMEOUT) of receiving a PING message.

If the client fails to send 2 consecutive PONG responses (missing heartbeats) as per above requirements, the server will consider the connection as stale and will terminate the connection.

Stale Connection

An active connection if not authenticated within 2 heartbeat cycles (60 seconds) will be deemed stale and therefore be closed.

Error Response and Codes

The general error response looks as follows:

event_type is the event that has the error. For example: in case of an error during auth, event_type is `auth_response`

// error respinse
{
    "event": "<event_type>",
    "status": "error",
    "error": {
        "error_code": 10001,
        "message": "Invalid authentication credentials"
    },
    "request_id": "my_sample_request_id"
}
Error Code Error Message
10001 Invalid authentication credentials
10002 Not authenticated
10003 Request not valid. Check the request again
10004 Subscription limit reached for this connection. Please open a new connection or close existing subscriptions
10005 Already subscribed for given parameter in the present connection
10006 Request unauthorized. Check api-key or ip again
10007 Streaming not supported for this account. Contact support if required
10008 Your IP is not whitelisted to access APIs. Please contact our Client Support
10009 Max connections breached
10010 Max new connections breached
99999 Something went wrong

Websocket Orders

This Document outlines the functionality of the Limit orders placed over the FalconX API. In order to access this functionality, each firm must have a set of API keys generated that has trading access enabled. For users that would like to access the FalconX API but do not yet have a set of API keys generated, please reach out to your FalconX Customer Rep or inquire on chat.

Currently supports limit orders only

API ENDPOINTS

The server implements websocket protocol

All the requests must be sent with the required action (Refer Order Requests). All the responses received will have an event field for various update events.

Clients can refer to sample websocket order clients here

https://github.com/falconxio/fx-ws-clients/

Creating a connection over WS

Open a websocket connection to wss://order.falconx.io/order via the websocket connect action.

Upon establishing websocket connection to the mentioned endpoint, Client should authenticate the connection before any actual action can be performed.

In case client tries to perform an action before the connection is authenticated, the request will be rejected with an "UnAuthorised error".

Authentication over WS

Generating an API key

Once you are signed up on FalconX, our customer success team will generate an API key for you. After generating the key you will have the following information which will be required for making any API request:

Please note: API Keys can also be generated by an Admin within a Client account. Clients can assign an Admin, who can then Generate API kets from Account Settings/Manage section. For more information please contact FalconX support.

SENDING AUTHENTICATION MESSAGE

The authentication message action=auth must contain the user identification credentials (api_key and passphrase) along with a signed message and current timestamp.

SIGNING THE MESSAGE

SAMPLE CODE

## Python Code
import base64
import hashlib
import hmac
import time
import json
secret = "secret"

def get_signature(self, timestamp, path):
  method = "GET"
  message = "".join([timestamp, method, path, ""])
  hmac_key = base64.b64decode(secret)
  signature = hmac.new(hmac_key, message.encode(), hashlib.sha256)
  signature_b64 = base64.b64encode(signature.digest())
  signature = signature_b64.decode("utf-8")
  return signature

timestamp = int(time.time())

signature = get_signature(str(timestamp), "/order")
req = {
  "action": "auth",
  "api_key": "api_key",
  "passphrase": "passphrase",
  "signature": signature,
  "timestamp": timestamp,
  "request_id": "my_request"
}

conn.send(data=json.dumps(req))

The signature field is generated by creating a SHA256 HMAC using the base64-decoded secret key on the pre-hash string timestamp + method + requestPath (where + represents string concatenation) and base64-encode the output. The timestamp value is the same as the FX-ACCESS-TIMESTAMP header.

The method should be UPPERCASE. While creating a websocket connection, the method would always be GET, and the requestPath would always be /order.

Remember to first base64-decode the alphanumeric secret string before using it as the key for HMAC. Also, base64-encode the digest output before sending in the header.

Please Note: A successful auth response will contain the sessionId upto 32 characters.

SAMPLE REQUEST:

{
  "action": "auth",
  "api_key": "xxyyzz",
  "passphrase": "aabbcc",
  "signature": "xt64fsrt18_uid",
  "timestamp": 16524352778,
  "request_id": "my_sample_request"
}

SAMPLE RESPONSE:

{
  "event": "auth_response",
  "status": "success",
  "request_id": "my_sample_request",
  "body": {
    "message": "Authentication successful",
    "session_id": "a1b2c3d4e5f6g7h8i9j10k11lm"
  }
}

Placing New Limit Orders

To initiate a new limit order, clients are required to dispatch a create_order_request message containing the necessary parameters for the trade.

New Order Request

{
  "action": "create_order_request",
  "request_id": "<Unique Identifier>",
  "order_type": "limit",
  "order_details": {
    "client_order_id": "<Client-Specified Identifier>",
    "base_token": "<Base Asset Symbol>",
    "quote_token": "<Quote Asset Symbol>",
    "quantity": <Amount of Asset>,
    "quantity_token": "<Token Denoting Quantity>",
    "limit_price": <Desired Limit Price>,
    "side": "<Order Direction: buy/sell>",
    "tif": "<Order Duration: e.g., gtc>"
    "expiry": "<expiry time in future>"
  }
}

Parameter Descriptions

Field Mandatory Type Detail
action Yes string Defines the intended action. Use create_order_request for order creation.
request_id string A request identifier for tracking the request and its corresponding response.
order_type Yes string Specifies the type of order, which should be limit for limit orders.
order_details Yes
client_order_id
 Yes string (uuid) A unique identifier set by the client for the create order request.
base_token
 Yes string The asset to be traded.
quote_token
 Yes string The pricing asset for the base token.
quantity
 Yes number The volume of the asset to be transacted.
quantity_token
 Yes string The token that represents the quantity measure. This can be either base or quote token depending on the client's usecase
limit_price
 Yes number The target price for each unit of the base asset. (This will in terms of quote token only)
side
 Yes string Indicates the trade direction, either buy or sell.
tif
 Yes string Time in Force, determining how long the order remains active (e.g., gtc for Good Till Canceled, gtx for Good Tilll Expiry time).
expiry
 - string (ISO format datetime) A valid expiry time in future (max 14 days in future, only required for gtx orders).

Example New Order Request

{
  "action": "create_order_request",
  "request_id": "10147082-80d5-3569-7246-7c040317c7c8",
  "order_type": "limit",
  "order_details": {
    "client_order_id": "853d5c4a-a20e-2d36-d6cc-2406bb0a6529",
    "base_token": "ETH",
    "quote_token": "USD",
    "quantity": 0.1,
    "quantity_token": "ETH",
    "limit_price": 3500,
    "side": "buy",
    "tif": "gtc"
  }
}

Please Note: GTC orders will have an inherent lifetime of 30days, post which the orders will expire.

Updating Limit Orders

To update an existing limit order, clients are required to dispatch an update_order_request message containing the necessary parameters to be edited for the order.

Please Note: it is not required to send all the fields in the request. Only the fields to be updated needs to be sent along with the mandatory identifiers.

Update Order Request

{
  "action":     "update_order_request",
  "request_id": "<Unique Identifier>",
  "order_type": "limit",
  "order_details": {
    "orig_client_order_id": "<Last successful client_order_id>",
    "client_order_id":      "<Unique id for update request>",
    "order_id":             "<FalconX Issued orderId>", //mandatory
    "quantity":             <Updated Amount of asset to be transacted>,
    "quantity_token":       "<Token denoting quantity>",
    "limit_price":          <Updated desired limit price>,
    "expiry":               "<Expiry time in future>",
}

Parameter Descriptions

Field Mandatory Type Detail
action Yes string Defines the intended action. Use update_order_request for order updation.
request_id string A request identifier for tracking the request and its corresponding response.
order_type Yes string Specifies the type of order, which should be limit for limit orders.
order_details Yes
order_id
 Yes string A FalconX issues order_id for a successfully accepted order (Refer to Responses below)
client_order_id
 Yes string (uuid) A unique identifier set by the client for the update request.
orig_client_order_id
 Yes The last successfully accepted client_order_id.
quantity
 - number Can be updated. If quantity is being updated, quantity_token must be passed and should be same as the original order.
quantity_token
 - string Required is quantity is being updated
limit_price
 - number Can be updated
expiry
 - string (ISO format datetime) Can be updated for gtx orders.

Only limit_price, quantity, expiry (if tif) can be modified.

Please Note: When trying an update operation, two identifiers are required from clients. orig_client_order_id which is the last successfully accepted client_order_id sent in either a create or update request. client_order_id is a new unique identifier for the current request.

Example Update Order Request

// Update Order Request
{
  "action":     "update_order_request",
  "request_id": "my_request_id_1234",
  "order_type": "limit",
  "order_details": {
    "orig_client_order_id": "853d5c4a-a20e-2d36-d6cc-2406bb0a6530",
    "client_order_id":      "853d5c4a-a20e-2d36-d6cc-2406bb0a6529",
    "order_id":             "9ff88a7cfa5a4c6a6cotec61680eb43", //mandatory
    "quantity":             0.0001,
    "quantity_token":       "BTC",
    "limit_price":          80000,
    "expiry":               "2024-05-01T00:00:00Z",
}

Cancel Order Request

// Cancel Order Request
{
  "action":     "cancel_order_request",
  "request_id": "<Unique Identifier>",
  "order_type": "limit",
  "order_details": {
    "orig_client_order_id": "<Last successful client_order_id>",
    "client_order_id":      "<Unique id for update request>",
    "order_id":             "<FalconX Issues orderId>", //mandatory
}

Parameter Descriptions

Field Mandatory Type Description
action Yes string Defines the intended action. Use cancel_order_request for order cancellation.
request_id string
order_type Yes string Specifies the type of order, which should be limit for limit orders.
order_details Yes
orig_client_order_id
 string The last successfully accepted client_order_id.
client_order_id
 string (uuid) A unique identifier set by the client for the update request.
order_id
 Yes string A FalconX issues order_id for a successfully accepted order (Refer to Responses below)

Example Cancel Request

// Example Cancel Request
{
  "action":     "cancel_order_request",
  "request_id": "my_request_id_1234",
  "order_type": "limit",
  "order_details": {
    "orig_client_order_id": "853d5c4a-a20e-2d36-d6cc-2406bb0a6530",
    "client_order_id":      "853d5c4a-a20e-2d36-d6cc-2406bb0a6529",
    "order_id":             "9ff88a7cfa5a4c6a6cotec61680eb43", //mandatory
}

Receiving Responses

Following the submission of a new/update/canel order requests the server will issue a response indicating whether the order was successfully created/updated/canceled respectively or if there was an error.

Successful Response Structure

// Successful response structure
{
  "status": "success",
  "event": "<event>",
  "request_id": "<request id>",
  "body": {
    "order_id": "<FalconX Issues orderId>",
    "client_order_id": "<Unique id sent for the current request>",
    "orig_client_order_id": "<Last successful client_order_id>",
    "token_pair": {
      "base_token": "<Base Asset Symbol>",
      "quote_token": "<Quote Asset Symbol>"
    },
    "quantity": {
      "token": "<Requested Quantity Token>",
      "value": <Requested Quantity>
    },
    "side": "<Requested side>",
    "order_type": "<Requested Ordertype>",
    "limit_price": <Client provided limit price>,
    "time_in_force": "<TIF for the order>",
    "order_status": "<Current status of the order>",
    "fills": [  // only in case of fills
      {
        "fx_quote_id": "<FalconX issued unique trade identifier>",
        "price": <Executed price for this fill>,
        "quantity": {
          "token": "<Fill Quantity token>",
          "value": <Fill Quantity Value>
        },
        "t_execute": "<Time of Fill>"
      }
    ]
  }
}

Example Response:

// Sample response
{
  "status": "success",
  "event": "create_order_ack",
  "request_id": "my_request_id_1234",
  "body": {
    "order_id": "9ff88a7cfa5a4c6a6cotec61680eb43",
    "client_order_id": "853d5c4a-a20e-2d36-d6cc-2406bb0a6529",
    "token_pair": {
      "base_token": "BTC",
      "quote_token": "USD"
    },
    "quantity": {
      "token": "BTC",
      "value": 0.001
    },
    "side": "sell",
    "order_type": "limit",
    "limit_price": 50000,
    "time_in_force": "gtc",
    "order_status": "OPEN"
  }
}

Events

Event Description
auth_response Response for auth request
create_order_ack Response for a successfully accepted create order request
update_order_ack Response for a successfully accepted update order request
cancel_order_ack Response for a successfully accepted cancel order request
order_update Order update for any subsequent updates - fill, expiry etc.
order_rejected Order reject message on error

Order Statuses

Order Status Description
OPEN Order has been accepted and active
EXPIRED Order has expired
CANCELED Order has been canceled by user
PARTIALLY_FILLED Partially Filled and active
PARTIALLY_FILLED_AND_EXPIRED Partially Filled and Expired due to timeout
PARTIALLY_FILLED_AND_CANCELED Partially Filled and Canceled by user
REJECTED Order was rejected due to error

Error Response Structure

// Error Response Structure
{
  "event": "order_rejected",
  "status": "success",
  "request_id": "my_request_id_1234",
  "body": {
    "order_id": "<FalconX Issues orderId>",
    "client_order_id": "<Unique id sent for the current request>",
    "orig_client_order_id": "<Last successful client_order_id>",
    "token_pair": {
      "base_token": "<Base Asset Symbol>",
      "quote_token": "<Quote Asset Symbol>"
    },
    "quantity": {
      "token": "<Requested Quantity Token>",
      "value": <Requested Quantity>
    },
    "side": "<Requested side>",
    "order_type": "<Requested Ordertype>",
    "limit_price": <Client provided limit price>,
    "time_in_force": "<TIF for the order>",
    "order_status": "<Current status of the order>",
    "error": {
      "errors": {
        "code": "<Error Code>",
        "reason": "<Error reason>"
      },
      "success": false
    }
  }
}

It is imperative for clients to implement mechanisms to handle both successful and erroneous responses based on the server's feedback.

Error Codes

Error Code Error Message
10001 Invalid authentication credentials
10002 Not authenticated
10003 Request not valid. Check the request again
10004 Subscription limit reached for this connection. Please open a new connection or close existing subscriptions
10005 Already subscribed for given parameter in the present connection
10006 Request unauthorized. Check api-key or ip again
10007 Streaming not supported for this account. Contact support if required
10008 Your IP is not whitelisted to access APIs. Please contact our Client Support
10009 Max connections breached
10010 Max new connections breached
99999 Something went wrong

For other order related error codes. Refer to https://app.falconx.io/docs/rfq-rfs#requests

Error Management

In the event of an error, the server will supply an error code alongside a descriptive message. Clients are expected to manage these errors judiciously. Common error scenarios include invalid input, authentication issues, and exceeding rate limits.

Rate Limiting Policies

Clients should be cognizant of any rate limits enforced by the server to prevent misuse. Breaching these limits could lead to temporary or permanent restrictions on service access.

Conclusion

This documentation delineates the protocol for placing limit orders via Websocket. Adherence to the outlined message formats and response handling procedures is crucial. For additional support or clarification, clients are encouraged to reach out to their FalconX Customer Rep or inquire on chat.

python javascript