Get account

curl

ADDR=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
curl "https://api.arcus.xyz/v1/account?address=${ADDR}"

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.arcus.xyz/v1/account",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.arcus.xyz/v1/account"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.arcus.xyz/v1/account")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "accountIndex": 4,
  "address": "<string>",
  "netQuoteBalance": "100000",
  "equity": "<string>",
  "freeCollateral": "<string>",
  "netDeposits": "100000",
  "pendingDeposits": "<string>",
  "pendingWithdrawals": "<string>",
  "positions": {},
  "sequenceNumber": 123,
  "netDepositsByAsset": [
    {
      "spotAssetId": 123,
      "spotAssetDisplayName": "<string>",
      "netAmount": "<string>"
    }
  ],
  "loanBalance": "100",
  "unsettledInterest": "0.25",
  "marginState": "healthy",
  "borrowHeadroom": "150",
  "spotPositions": {}
}

{
  "error": "Invalid request body",
  "code": "GEO_RESTRICTED"
}

{
  "error": "Invalid request body",
  "code": "GEO_RESTRICTED"
}

{
  "error": "rate limited",
  "reason": "account_empty",
  "retryAfterMs": 850,
  "clientId": "my-order-42"
}

GET

account

curl

ADDR=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
curl "https://api.arcus.xyz/v1/account?address=${ADDR}"

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.arcus.xyz/v1/account",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.arcus.xyz/v1/account"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.arcus.xyz/v1/account")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "accountIndex": 4,
  "address": "<string>",
  "netQuoteBalance": "100000",
  "equity": "<string>",
  "freeCollateral": "<string>",
  "netDeposits": "100000",
  "pendingDeposits": "<string>",
  "pendingWithdrawals": "<string>",
  "positions": {},
  "sequenceNumber": 123,
  "netDepositsByAsset": [
    {
      "spotAssetId": 123,
      "spotAssetDisplayName": "<string>",
      "netAmount": "<string>"
    }
  ],
  "loanBalance": "100",
  "unsettledInterest": "0.25",
  "marginState": "healthy",
  "borrowHeadroom": "150",
  "spotPositions": {}
}

{
  "error": "Invalid request body",
  "code": "GEO_RESTRICTED"
}

{
  "error": "Invalid request body",
  "code": "GEO_RESTRICTED"
}

{
  "error": "rate limited",
  "reason": "account_empty",
  "retryAfterMs": 850,
  "clientId": "my-order-42"
}

The response body shown here is a static example, not live data. After you click Send, your live result appears in a separate panel headed 200 OK. The panel under the status-code tabs is a fixed sample from the spec — its field values (fees, prices, sizes, IDs, timestamps) are placeholders. Use Send, or call the endpoint, for current values.

Returns account information for the requested address, including balances, collateral, and open positions. No authentication header is required.

Query Parameters

address

string

required

Master Ethereum address for this API key (must match address from POST /createApiKey for the same key). Required on REST for account-scoped reads and for place/cancel. Invalid hex → 400; mismatch with key → 403.

20-byte EVM address as hex: optional 0x or 0X prefix and exactly 40 hexadecimal digits. API responses normalize to lowercase a–f after 0x.

Pattern: ^(0x|0X)?[0-9a-fA-F]{40}$

accountIndex

integer

default:0

Subaccount index (0–9) to scope the request to. Defaults to 0 (the primary account). Values above 9 → 400.

Required range: 0 <= x <= 9

Response

Account details.

Account state including balances, collateral, and open positions. Returned by GET /account. Orders are served via the dedicated orders channel/endpoint.

accountIndex

integer

required

Account index (account index, 0–9). Identifies the account for orders, positions, fills, and API keys.

Required range: 0 <= x <= 9

address

string

required

Ethereum address associated with the account.

Pattern: ^(0x|0X)?[0-9a-fA-F]{40}$

netQuoteBalance

string

required

Account's aggregate cash balance as of the last event, in full quote currency (decimal string). Equals Account.QuoteBalance + Σ Position.QuoteBalance (cross-margin scope). Changes only on external cash flows: deposits, withdrawals, fill cash flows (-sizeDelta × fillPrice), trading fees, and funding settlements. Internal margin reallocations leave it unchanged. Combine with live oracle prices to derive equity: equity = netQuoteBalance + Σ (size × oracle).

Examples:

"100000"

"-25.5"

equity

string

required

Total account equity in full quote currency (decimal string). Computed as netQuoteBalance + Σ (size × mark) over all open positions. May differ from the engine's netQuoteBalance snapshot between fills as mark prices move.

freeCollateral

string

required

Collateral available for trading in full quote currency (decimal string). Computed as equity − Σ initial_margin_required across open positions.

Spot collateral value is excluded — it is not order margin (borrow capacity against it is LTV-bounded). When the lending section is present equity includes spot collateral value but freeCollateral does not, so an account backed by spot collateral can show 0 or a negative freeCollateral while marginState is healthy. Use marginState and borrowHeadroom for loan-aware headroom.

netDeposits

string

required

Lifetime net USDG deposits in full quote currency (decimal string): cumulative inflows minus cumulative outflows across every applied account transfer — deposits, withdrawals, internal transfers, self transfers between your own account indices, and referral claims. Rejected transfers, spot-asset flows (see netDepositsByAsset), and engine-originated lending cash legs (interest settlements, draws) are excluded.

This is the capital you have put in, not what it is worth now. Unlike equity and freeCollateral it does not move with oracle prices; only a transfer changes it. Subtract it from equity for all-time PnL — the same basis GET /portfolio uses, so the two agree.

Examples:

"100000"

"-25.5"

pendingDeposits

string

required

Pending deposit amount.

pendingWithdrawals

string

required

Pending withdrawal amount.

positions

object

required

Open positions keyed by marketId (integer; 1=BTC-USD, 2=ETH-USD, etc). JSON keys are stringified integers.

Show child attributes

sequenceNumber

integer<uint64>

required

Last processed engine sequence number for this account. Clients can use this to filter duplicate diffs and reconcile against streaming AccountUpdate events on the accounts channel.

netDepositsByAsset

object[]

Lifetime net deposits broken out per collateral asset, sorted by spotAssetId. The spotAssetId 0 (USDG) entry always equals netDeposits. Spot entries are quantities in the asset's own units — value them with a price series of your choosing (pricing a past flow is a cost-basis question). Omitted for accounts with no transfer history.

Show child attributes

loanBalance

string

Outstanding loan principal in full quote currency (decimal string). Present only for accounts with a lending footprint — a loan history, an active wind-down, or spot collateral holdings; all other accounts keep the exact pre-lending response shape (this and the other lending fields are omitted). When the lending section is present, equity includes spot collateral value and deducts unsettledInterest, and freeCollateral deducts unsettledInterest.

Examples:

"100"

"0"

unsettledInterest

string

Borrow interest accrued since the account's last settlement and not yet debited from cash, in full quote currency (decimal string): loanBalance × (global borrow index − account's settlement cursor). Grows as the global index advances and snaps back toward 0 when the engine settles it (the debit then appears in netQuoteBalance) — a delta since last settle, NOT a lifetime interest total. Part of the lending section — omitted for accounts without one.

Example:

"0.25"

marginState

enum<string>

Loan-aware margin verdict. healthy: new risk (orders, borrows, withdrawals) is admitted. unhealthy: the initial-margin check fails — no new risk, but no liquidation either (that triggers on the maintenance side). inWindDown: the account is a frozen estate being liquidated after a borrower-liquidation trigger. Part of the lending section — omitted for accounts without one.

Available options:

healthy,

unhealthy,

inWindDown

borrowHeadroom

string

How much additional loan need the account's current collateral could absorb, in full quote currency (decimal string): max(0, initial loan capacity − current loan need). 0 when the account is at or beyond its initial LTV bound. Part of the lending section — omitted for accounts without one.

Examples:

"150"

"0"

spotPositions

object

Spot collateral holdings keyed by spotAssetId (stringified integer; separate namespace from perp market ids). Only open holdings (size > 0) appear. Part of the lending section — omitted for accounts without one.

Show child attributes

API documentation

Endpoints

WebSocket

Changelog

Query Parameters

Response