Accounts

Account Balances

Get account balances

GET /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 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

200: OK Account balances information

{
    "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
            },
            ...
        ]
    }
}

500: Internal Server Error Something went wrong, contact support

401: Unauthorized Not authorized

Get all user accounts

GET /api/accounts/

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

200: OK

[
  {
    "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": "********************"
  },
]

Create an account for an exchange

POST /api/accounts/

Name must be unique under each user.

Request Body

Name	Type	Description
name*		name of account
api_key*	String	API key for exchange
api_secret*	String	API secret for exchange
password	String	password for exchange if required
exchange*	String	valid name of Exchange

200: OK Account balances information

{
    "message": "Successfully created abcdef"
}

500: Internal Server Error Something went wrong, contact support

401: Unauthorized Not authorized

400: Bad Request Invalid request ex. missing required fields

Archive account

DELETE /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*	string	name of account

200: OK Account balances information

{
    "message": "Successfully created abcdef"
}

500: Internal Server Error Something went wrong, contact support

401: Unauthorized Not authorized

400: Bad Request Invalid request ex. missing required fields

Update account

PUT /api/accounts/

Update some subset of fields

Request Body

Name	Type	Description
id*	string	uuid of primary key
margin_mode	string	one of ISOLATED, CROSS, CASH

200: OK Account balances information

{
    "message": "Successfully created abcdef"
}

500: Internal Server Error Something went wrong, contact support

401: Unauthorized Not authorized

400: Bad Request Invalid request ex. missing required fields

Set Leverage

POST /api/set_leverage/

Request Body

Name	Type	Description
leverage*	string	new leverage
pair	string	pair name
account_ids	list of strings	list of account ids

200: OK Account balances information

{
    "message": "Leverage changed successfully."
}

400: Bad Request Invalid request ex. missing required fields

401: Unauthorized Not authorized

422: Unprocessable Entity

Get cached account balances

GET /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")

200: OK Account balances information

{
  "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
    },
    ...
  ]
}