# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tread.fi/interacting-with-the-api/api-reference/accounts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.