REST APIs Documentation

Introduction

Defx offers both public and private REST APIs.

Public REST APIs provide market data such as:

• markets being traded

• price data for each market

• trade history

Private REST APIs allow you to manage both orders and funds:

• place and cancel orders

• see your currently active orders

• see your trading history

• see your currently active positions

---

Base URLs

Testnet

The Base URL for testnet is: api.testnet.defx.com

Mainnet

The Base URL for testnet is: api.defx.com

---

Authentication

Public APIs

Public APIs can be accessed without authentication using the GET method, where request parameters are embedded within the query string.

Private APIs

Defx uses API keys to allow access to private APIs. You can obtain these keys by logging in and creating a key in the Settings -> API section. Doing so will provide you with both an API Key (which will serve as your username) and an API Secret (which will be used to sign messages).

All requests to private endpoints must include the following headers:

Header	Description	VALUE
X-DEFX-APIKEY	API Key	Your unique Defx API key
X-DEFX-TIMESTAMP	Timestamp	The current time in milliseconds since the Unix epoch
X-DEFX-SIGNATURE	An HMAC-SHA256 signature, created using your API Secret	timestamp (in ms) + query string (sorted by key in asc order) + body (as JSON string with no spaces or newlines or escaped characters)

To prevent replay attacks, Defx requires that the timestamp in the request header be within 10 seconds of the server’s timestamp upon receiving the request. If the timestamp difference exceeds 10 seconds, the request will be considered unauthorized.

EXAMPLE

Assuming that the API key's value is API_KEY and the API secret's value is API_SECRET, a signature is first generated on your backend using the timestamp, query string (sorted ASC by key, and the body (as JSON string with no spaces, newlines or escaped characters) and the API secret.

sh
  echo -n '1707238375423userId=22&accountId=45{"symbol":"BTC_USDC","side":"SELL","type":"LIMIT","quantity":"1","price":"5500"}' | openssl dgst -sha256 -hmac 'API_SECRET'

  ef2fdcac638890ff7750e377c7697724cd259fd3c26b5a04806a26eb92478137

Once the signature is generated, this is sent as the header along with the payload as follows:

  curl --location 'https://api.defx.com/orders?userId=22&accountId=45' \
    --header 'X-DEFX-APIKEY: API_KEY' \
    --header 'X-DEFX-SIGNATURE: ef2fdcac638890ff7750e377c7697724cd259fd3c26b5a04806a26eb92478137' \
    --header 'X-DEFX-TIMESTAMP: 1707238375423' \
    --header 'Content-Type: application/json' \
    --data '{
        "symbol": "BTC_USDC",
        "side": "SELL",
        "type": "LIMIT",
        "quantity": "1",
        "price": "5500",
    }'

---

Rate Limits

Coming Soon

---

Data Types

Defx's public and private endpoints contain references to the following data types in the request object, and they are documented here for reference.

string

A sequence of characters enclosed in quotes, adhering to the standard JSON format. For further details, refer to the JSON specification.

decimal

A numeric value with a decimal point, encoded as a string in JSON. It consists of a sequence of digits, which may include a decimal point followed by more digits.

timestamp

Represents the time elapsed since January 1, 1970, UTC, measured in milliseconds. This value is a multiplication of the UNIX timestamp by 1000 and is expressed as a numerical value in JSON, not as a string.

integer

A whole number presented as a numerical value in JSON.

array

A structured list in JSON format, where each element may contain a described payload.

---

HTTP Status Codes

HTTP Status	Description
200	Request was successful
30x	API endpoint has moved
400	There was an issue with the request format. When a 400 status is returned, you will receive the exact error as part of the response body to help you understand the nature of this error.
401	The API key is missing the role necessary to access this private API endpoint
404	Unknown API entry point or Order not found
429	Rate Limiting was applied
500	The server encountered an error
502	Technical issues are preventing the request from being satisfied
503	The exchange is down for maintenance