# 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 <a href="#authentication" id="authentication"></a>

### **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:

| 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 <a href="#payload" id="payload"></a>

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 <a href="#rate-limits" id="rate-limits"></a>

Coming Soon

***

## Data Types <a href="#data-types" id="data-types"></a>

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                                                                                                                                                      |
