> For the complete documentation index, see [llms.txt](https://docs.tread.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tread.fi/interacting-with-the-api/api-reference/accounts.md).

# Accounts

## Account Balances

## Get account balances

<mark style="color:blue;">`GET`</mark> `/api/balances/`

Get token balances and positions in your configured accounts.  Identity is inferred by API token.

#### Path Parameters

| Name           | Type            | Description                                                                             |
| -------------- | --------------- | --------------------------------------------------------------------------------------- |
| account\_names | list of strings | Optional. If specified, only balances for the accounts in this parameter are retrieved. |

Refer to MarketType and AssetType in [Type Reference](/interacting-with-the-api/api-reference/type-reference.md) for more details on these balance attributes.

**notional\_pct\_total** - calculated as the ratio of notional against total notional for all assets within the same market\_type

{% tabs %}
{% tab title="200: OK Account balances information" %}

```javascript
{
    "AccountABC": {
        "exchange": "Bybit",
        "assets": [
            {
                "symbol": "ETH:PERP-USDT",
                "size": 1.69,
                "notional": 3051.5284,
                "market_type": "perp",
                "asset_type": "position",
                "unrealized_profit": 24.6772,
                "initial_margin": 306.80066534,
                "maint_margin": 16.90546734,
                "margin_balance": 298.90609459,
                "leverage": 10.0,
                "notional_pct_total": 0.994565
            },
            {
                "symbol": "USDT",
                "size": 275.56989474,
                "notional": 275.569895,
                "market_type": "unified",
                "asset_type": "token",
                "unrealized_profit": 23.33619985,
                "initial_margin": 308.47710954,
                "maint_margin": 17.08121552,
                "margin_balance": 298.90609459,
                "leverage": null,
                "notional_pct_total": 0.817474
            },
            ...
        ]
    },
    "Account123": {
        "exchange": "Binance",
        "assets": [
            {
                "symbol": "USDT",
                "size": 1414.06039641,
                "notional": 1414.060396,
                "market_type": "perp",
                "asset_type": "token",
                "unrealized_profit": 11.02638782,
                "initial_margin": 155.72429442,
                "maint_margin": 3.32015061,
                "margin_balance": 1425.08678423,
                "leverage": null,
                "notional_pct_total": 0.6449
            },
            {
                "symbol": "BTC:PERP-USDT",
                "size": 0.021,
                "notional": 572.956735,
                "market_type": "perp",
                "asset_type": "position",
                "unrealized_profit": 7.87343483,
                "initial_margin": 114.59134696,
                "maint_margin": 2.29182693,
                "margin_balance": null,
                "leverage": 5.0,
                "notional_pct_total": 0.261304
            },
            ...
        ]
    }
}
```

{% endtab %}

{% tab title="500: Internal Server Error Something went wrong, contact support" %}

```javascript
{
    "message": "Something went wrong..."
}
```

{% endtab %}

{% tab title="401: Unauthorized Not authorized" %}

```javascript
{
    "message": "Invalid credentials"
}
```

{% endtab %}
{% endtabs %}

## Get all user accounts

<mark style="color:blue;">`GET`</mark> `/api/accounts/`&#x20;

#### Path Parameters

| Name              | Type   | Description                                  |
| ----------------- | ------ | -------------------------------------------- |
| include\_archived | string | include archived accounts if field is "true" |

#### Response Body

| Field Name          | Type    | Description                                             |
| ------------------- | ------- | ------------------------------------------------------- |
| id                  | string  | Unique identifier for the account                       |
| name                | string  | Name of the account                                     |
| user                | integer | User ID associated with the account                     |
| username            | string  | Username for the account                                |
| exchange            | string  | Name of the exchange                                    |
| margin\_mode        | string  | Margin mode of the account                              |
| created\_at         | string  | Timestamp of when the account was created               |
| credential\_options | object  | Options for account credentials                         |
| vcefi\_enabled      | boolean | Indicates if VCEFI is enabled                           |
| archived            | boolean | Indicates if the account is archived                    |
| wallet\_type        | string  | Type of the wallet, if applicable                       |
| wallet\_provider    | string  | Provider of the wallet, if applicable                   |
| vault\_address      | string  | Vault address, if applicable                            |
| egress\_ip          | string  | Egress IP address, if applicable                        |
| api\_key            | string  | API key for the account                                 |
| api\_secret         | string  | API secret for the account, masked for security reasons |
| password            | string  | Password for the account, masked for security reasons   |

{% tabs %}
{% tab title="200: OK" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>[
</strong><strong>  {
</strong>    "id": "4be4cba9-23ea-453a-a235-f2c8e1ba7d51",
    "name": "test",
    "user": 2,
    "username": "yibo",
    "exchange": "Gate",
    "margin_mode": "CROSS",
    "created_at": "2025-10-08T21:27:09.473156Z",
    "credential_options": {
      "unified": true,
      "spot": true,
      "futures": true,
      "default": false
    },
    "vcefi_enabled": false,
    "archived": false,
    "wallet_type": null,
    "wallet_provider": null,
    "vault_address": null,
    "egress_ip": null,
    "api_key": "af46c013cb9a5a321a54564b",
    "api_secret": "********************",
    "password": "********************"
  },
<strong>]
</strong></code></pre>

{% endtab %}
{% endtabs %}

## Create an account for an exchange

<mark style="color:green;">`POST`</mark> `/api/accounts/`

Name must be unique under each user.

#### Request Body

| Name                                          | Type   | Description                                                                                       |
| --------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| name<mark style="color:red;">\*</mark>        |        | name of account                                                                                   |
| api\_key<mark style="color:red;">\*</mark>    | String | API key for exchange                                                                              |
| api\_secret<mark style="color:red;">\*</mark> | String | API secret for exchange                                                                           |
| password                                      | String | password for exchange if required                                                                 |
| exchange<mark style="color:red;">\*</mark>    | String | valid name of [Exchange](/interacting-with-the-api/api-reference/type-reference.md#exchange-enum) |

{% tabs %}
{% tab title="200: OK Account balances information" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>{
</strong>    "message": "Successfully created abcdef"
}
</code></pre>

{% endtab %}

{% tab title="500: Internal Server Error Something went wrong, contact support" %}

```javascript
{
    "message": "Something went wrong..."
}
```

{% endtab %}

{% tab title="401: Unauthorized Not authorized" %}

```javascript
{
    "message": "Invalid credentials"
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid request ex. missing required fields" %}

{% endtab %}
{% endtabs %}

## Archive account

<mark style="color:red;">`DELETE`</mark> `/api/accounts/`

Soft delete the account.  It will no longer be usable but reference to orders will be maintained.\
It will also be renamed to indicate it is archived:\
ex. {account\_name}\_*archived*\_{uuid}

#### Request Body

| Name                                   | Type   | Description     |
| -------------------------------------- | ------ | --------------- |
| name<mark style="color:red;">\*</mark> | string | name of account |

{% tabs %}
{% tab title="200: OK Account balances information" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>{
</strong>    "message": "Successfully created abcdef"
}
</code></pre>

{% endtab %}

{% tab title="500: Internal Server Error Something went wrong, contact support" %}

```javascript
{
    "message": "Something went wrong..."
}
```

{% endtab %}

{% tab title="401: Unauthorized Not authorized" %}

```javascript
{
    "message": "Invalid credentials"
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid request ex. missing required fields" %}

{% endtab %}
{% endtabs %}

## Update account

<mark style="color:$warning;">`PUT`</mark> `/api/accounts/`

Update some subset of fields

#### Request Body

| Name                                 | Type   | Description                  |
| ------------------------------------ | ------ | ---------------------------- |
| id<mark style="color:red;">\*</mark> | string | uuid of primary key          |
| margin\_mode                         | string | one of ISOLATED, CROSS, CASH |

{% tabs %}
{% tab title="200: OK Account balances information" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>{
</strong>    "message": "Successfully created abcdef"
}
</code></pre>

{% endtab %}

{% tab title="500: Internal Server Error Something went wrong, contact support" %}

```javascript
{
    "message": "Something went wrong..."
}
```

{% endtab %}

{% tab title="401: Unauthorized Not authorized" %}

```javascript
{
    "message": "Invalid credentials"
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid request ex. missing required fields" %}

{% endtab %}
{% endtabs %}

## Set Leverage

<mark style="color:$success;">`POST`</mark> `/api/set_leverage/`

#### Request Body

| Name                                       | Type            | Description         |
| ------------------------------------------ | --------------- | ------------------- |
| leverage<mark style="color:red;">\*</mark> | string          | new leverage        |
| pair                                       | string          | pair name           |
| account\_ids                               | list of strings | list of account ids |

{% tabs %}
{% tab title="200: OK Account balances information" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>{
</strong>    "message": "Leverage changed successfully."
}
</code></pre>

{% endtab %}

{% tab title="400: Bad Request Invalid request ex. missing required fields" %}

```json
{
    "errors": ["account_ids must be an array of strings"]
}
```

{% endtab %}

{% tab title="401: Unauthorized Not authorized" %}

```javascript
{
    "message": "Invalid credentials"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity" %}

```javascript
{
    "message": "Failed to set leverage"
}
```

{% endtab %}
{% endtabs %}

## Get cached account balances

<mark style="color:blue;">`GET`</mark> `/api/sor/get_cached_account_balance`

#### **Query Paramers:**

| Field Name      | Type   | Description                                                                                                                  |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `account_names` | string | Comma-separated list of account display names to filtert by. If not provided, return balances of all accounts owned by user. |

#### **Response Body:**

#### Top-Level Response Fields

| Field Name | Type           | Nullable | Purpose                                                                       |
| ---------- | -------------- | -------- | ----------------------------------------------------------------------------- |
| `balances` | array (object) | No       | Array of account balance objects, one per exchange account                    |
| `errors`   | array (object) | No       | Array of error objects for accounts that failed to fetch (empty if no errors) |

***

#### Balance Object Fields

| Field Name         | Type              | Nullable | Purpose                                                                          |
| ------------------ | ----------------- | -------- | -------------------------------------------------------------------------------- |
| `exchange_name`    | string            | No       | Name of the exchange (e.g., "Bybit", "OKXDEX", "Binance")                        |
| `account_name`     | string            | No       | Display name of the account/credential                                           |
| `user_id`          | number (integer)  | No       | User ID who owns this account                                                    |
| `account_id`       | string (UUID)     | No       | Unique identifier for the exchange credential                                    |
| `username`         | string            | No       | Username of the account owner                                                    |
| `equity`           | string (decimal)  | Yes      | Total account equity across all market types (decimal as string)                 |
| `assets`           | array (object)    | No       | Array of asset objects (tokens and positions) held in this account               |
| `equities`         | array (object)    | No       | Array of equity objects, grouped by market type (spot, perp, etc.)               |
| `transfers`        | array (object)    | No       | Array of transfer history objects (deposits/withdrawals)                         |
| `timestamp_millis` | number (integer)  | No       | Timestamp when the balance data was retrieved, in milliseconds since epoch (UTC) |
| `created_at`       | string (ISO 8601) | No       | Timestamp when the account credential was created                                |
| `vcefi_enabled`    | boolean           | No       | Whether vCEFI (virtual CEX) is enabled for this account                          |

***

#### Asset Object Fields

Each asset represents either a token balance or a position (for perpetual futures).

| Field Name          | Type                   | Nullable | Purpose                                                                                                                               |
| ------------------- | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `symbol`            | string                 | No       | Asset symbol (e.g., "BTC", "ETH", "LINK:PERP-USDT" for positions)                                                                     |
| `amount`            | string (decimal)       | No       | Quantity/amount of the asset (decimal as string). For positions, this is the position size (can be negative for short positions)      |
| `margin_balance`    | string (decimal)       | Yes      | Margin balance for this asset (decimal as string, nullable). For unified margin accounts, this may represent the total margin balance |
| `unrealized_profit` | string (decimal)       | Yes      | Unrealized profit/loss for positions (decimal as string, nullable). Zero or null for tokens                                           |
| `notional`          | string (decimal)       | Yes      | Notional value of the asset (decimal as string, nullable). For positions, this is position value                                      |
| `wallet_type`       | string                 | No       | Wallet type (e.g., "unified", "spot", "margin", "futures")                                                                            |
| `asset_type`        | string                 | No       | Type of asset: "token" for token balances, "position" for perpetual futures positions                                                 |
| `funding_fee`       | number (float) or null | Yes      | Funding fee for perpetual positions (number or null). Only present for positions with `asset_type: "position"`                        |
| `borrowed`          | string (decimal)       | Yes      | Amount borrowed (decimal as string, nullable). Used for margin trading                                                                |
| `initial_margin`    | string (decimal)       | Yes      | Initial margin requirement (decimal as string, nullable). Only relevant for leveraged positions                                       |
| `maint_margin`      | string (decimal)       | Yes      | Maintenance margin requirement (decimal as string, nullable). Only relevant for leveraged positions                                   |
| `leverage`          | string (decimal)       | Yes      | Leverage used for this position (decimal as string, nullable). Only relevant for leveraged positions                                  |
| `margin_mode`       | string                 | Yes      | Margin mode (e.g., "CROSS", "ISOLATED", "SPOT\_ISOLATED", nullable). Only relevant for certain exchanges and margin types             |

**Note:** For token assets (`asset_type: "token"`), fields like `funding_fee`, `borrowed`, `initial_margin`, `maint_margin`, `leverage`, and `margin_mode` are typically `null`. For position assets (`asset_type: "position"`), these fields may have values.

***

#### Equity Object Fields

Equity objects represent total equity grouped by market type.

| Field Name     | Type             | Nullable | Purpose                                               |
| -------------- | ---------------- | -------- | ----------------------------------------------------- |
| `total_equity` | string (decimal) | No       | Total equity for this market type (decimal as string) |
| `market_type`  | string           | No       | Market type (e.g., "spot", "perp", "futures")         |

{% tabs %}
{% tab title="200: OK Account balances information" %}

```javascript
{
  "balances": [
    {
      "exchange_name": "OKXDEX",
      "account_name": "acc123",
      "user_id": 13,
      "assets": [],
      "equities": [
        {
          "total_equity": "0",
          "market_type": "spot"
        }
      ],
      "equity": "0",
      "account_id": "b82512b5-450f-4329-9943-0e037d0782b2",
      "timestamp_millis": 1769078743904,
      "username": "integ_test",
      "transfers": [],
      "vcefi_enabled": false
    },
    {
      "exchange_name": "Bybit",
      "account_name": "acc456",
      "user_id": 13,
      "assets": [
        {
          "symbol": "BTC",
          "amount": "1.7E-7",
          "margin_balance": "1.7E-7",
          "unrealized_profit": "0",
          "notional": "0.015296464",
          "wallet_type": "unified",
          "asset_type": "token",
          "funding_fee": null,
          "borrowed": null,
          "initial_margin": "0",
          "maint_margin": "0",
          "leverage": null,
          "margin_mode": null
        },
        ...
        {
          "symbol": "ETH:PERP-USDT",
          "amount": "-0.1400000000000000000000",
          "margin_balance": "169685.78635621",
          "unrealized_profit": "11.2745659",
          "notional": "-420.343",
          "wallet_type": "unified",
          "asset_type": "position",
          "funding_fee": 0.18134707,
          "borrowed": null,
          "initial_margin": "42.29542862",
          "maint_margin": "2.36284362",
          "leverage": "10",
          "margin_mode": null
        },
      ],
      "equities": [
        {
          "total_equity": "267387.34548772",
          "market_type": "unified"
        }
      ],
      "equity": "267387.34548772",
      "account_id": "2fd72fdc-e010-400f-886c-2e45fa0104c4",
      "timestamp_millis": 1769078266235,
      "username": "test123",
      "transfers": [],
      "vcefi_enabled": true
    },
    ...
  ]
}
```

{% endtab %}
{% endtabs %}