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 More (on the top navigation) -> 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:
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
For the examples, assuming that the API key's value is API_KEY and the API secret's value is API_SECRET.
The signature is a HMAC-SHA256 hash generated using your API_SECRET on a concatenated string consisting of the timestamp, query string (if applicable), and the request body. The request_body should be a json string with no spaces, newlines or escaped characters.
1. Standard Request (No Query Parameters)
Use this example for the majority of API calls where data is passed only in the request body.
Signature Generation String: Concatenate the timestamp and the raw JSON body (with no spaces or newlines). TIMESTAMP + JSON_BODY
Example:
Timestamp:
1707238375423Request Body:
{"symbol":"BTC_USDC","side":"SELL","type":"LIMIT","quantity":"1","price":"5500"}
Once the signature is generated, this is sent as the header along with the payload as follows:
2. Complex Request (With Query Parameters)
Use this example for specific endpoints that require URL parameters. To prevent tampering, the query string must be included in the signature. The query string must be sorted alphabetically by key.
Signature Generation String: Concatenate the timestamp, the sorted query string, and the raw JSON body. TIMESTAMP + QUERY_STRING
Example:
Timestamp:
1707238375423Query Params:
idType=clientOrderId&symbol=BTC_USDC(Sorted ASC by key)Request Body: (Empty)
Signature Generation:
Final Request:
Important Notes
Alphabetical Sorting: Query parameters in the URL must always be sorted in ascending order (A-Z) by their keys before generating the signature.
JSON Formatting: When a body is present, use the raw JSON string with no spaces, newlines, or escaped characters for the signature.
Combined Requests: If a request requires both a query string and a body, the signature string is formed by
TIMESTAMP + QUERY_STRING + BODY.
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
Last updated