> This page is for Trading.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.immix.xyz/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.immix.xyz/_mcp/server.

# Get the capital view

GET /risk/capital

The organisation's capital view: per account once `ACTIVE` and not deleted, what its margin wallets could shed and stay `NORMAL` under every limit, what the limits would let leave and the top-up back to `NORMAL`; then totals by venue and location. A query parameter is 400, `minGlobalSequence` aside; without the surface, 503 `RISK_UNAVAILABLE`. Needs `risk:read` or any `risk` capability.

Reference: https://docs.immix.xyz/trading/api-reference/rest-api/risk/get-capital

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Query parameters

- `minGlobalSequence` (string, optional) — A position you hold — an `X-Immix-Global-Sequence` you read, or a 202's `commandGlobalSequence`: this member answers only once it has folded the platform's stream through it, waiting up to its deadline, then 503 `PROJECTION_BEHIND` with `Retry-After`. Within that stream a read is never older than what you have seen; drop your positions after an announced stream cut. A retry stating its 202's position attaches to or replays that operation while the journal holds its key, never publishing twice. Stated once: one to nineteen digits, at most 9223372036854775807; else 400 `MALFORMED_REQUEST`.

### Headers

- `X-Request-Id` (string, optional) — Your own id for the request: 8 to 128 of `[A-Za-z0-9._-]`. It becomes the request's id and is echoed on the response. A value off that grammar is replaced with a fresh id, never refused.

## Response

### 200

The capital view: the accounts, account ascending, then the totals by venue and by location, keys ascending. The position the headers state and the body restates was taken before the rows were read, so a row that moved meanwhile is newer than it, never older.

- `globalSequence` (string, required) — The position as a decimal string — the last change this member had applied, orders, balance readings and algo instances included.
- `accounts` (list of RiskCapitalRow, required) — One row per account of the organisation that has been `ACTIVE` and is not deleted — a disabled one included; one still `PENDING_APPROVAL` or `DRAFT` has no posture yet and no row — account ascending.
- `byVenue` (list of RiskCapitalTotal, required) — The totals by venue, keyed by the venue's name, keys ascending.
- `byLocation` (list of RiskCapitalTotal, required) — The totals by location — `CUSTODIAN` (the custody share) and `EXCHANGE` — keys ascending.

## Errors

### 400 Get Capital Risk Request Bad Request Error

The request's shape is wrong: a non-positive id, an unknown `view` or filter value, a query string that does not decode, a query parameter the operation does not take, or a cursor that does not decode or came from another query (`INVALID_CURSOR`). No position rides a refusal that consulted no state.

- `error` (ErrorBody, required) — What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
- `currentVersion` (string, optional) — On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance's config write: the row's current version (the `ETag` carries the same token) — re-read, reapply, retry.

### 401 Get Capital Risk Request Unauthorized Error

No bearer token, or one that does not verify.

- `error` (ErrorBody, required) — What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
- `currentVersion` (string, optional) — On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance's config write: the row's current version (the `ETag` carries the same token) — re-read, reapply, retry.

### 403 Get Capital Risk Request Forbidden Error

`CAPABILITY_DENIED`: a read your capabilities do not cover, or a staging route without its propose bit (`accounts:propose`). `NOT_REGISTERED`: no row or open invitation at your verified address, an unknown organisation, or an unclaimed row (an administrator admits it). `EMAIL_UNVERIFIED`: verify, then sign in again. `INVITATION_EXPIRED`: an administrator re-invites. `FORBIDDEN_PRINCIPAL`: no `org_id`, a non-ASCII ref, a disabled user, a binding with no user. `ORG_NOT_ACTIVE`: disabled, pending or deleted. Owners' 403s carry the position header and `Idempotent-Replay`.

- `error` (ErrorBody, required) — What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
- `currentVersion` (string, optional) — On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance's config write: the row's current version (the `ETag` carries the same token) — re-read, reapply, retry.

### 503 Get Capital Risk Request Service Unavailable Error

This member cannot serve the risk reads now: `NOT_PRIMED` — still catching up; retry shortly — `PROJECTION_BEHIND` — behind your `minGlobalSequence`; retry after `Retry-After` — or `RISK_UNAVAILABLE` — deployed without the reads the route serves (the limits, the postures or the adjustments), so a retry here changes nothing; every other route is unaffected. A limit or adjustment write can also meet the door's 503s every write can: `NOT_SERVING`, `OWNER_ABSENT`, or a command lost in transit — nothing was journaled; retry against a serving member.

- `error` (ErrorBody, required) — What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
- `currentVersion` (string, optional) — On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance's config write: the row's current version (the `ETag` carries the same token) — re-read, reapply, retry.

## Types

### RiskCapitalRow

One account's row of the capital view: its venue and location, its posture and arm repeated from the postures, the valuation its latest published record states, and the three figures derived from them at the read — what the margin wallets could shed, what the limits would let leave, what is owed to return to NORMAL. A derivation, not a published fact: it moves with every record and limit the gateway folds.

- `accountId` (integer, required) — The account (`GET /accounts`).
- `venue` (string, required) — The venue's name (`okx`, `anchorage`), as `GET /venue-key-specs` names it; `exchange:<id>` at a venue the catalogue does not name.
- `location` (enum, required) — Where the account's capital sits: at an exchange, or in a custodian's vault — the venue's kind, as the venue specs publish it.
  - Allowed values: `EXCHANGE`, `CUSTODIAN`
- `posture` (enum, required) — The account's posture (`GET /risk/postures`), repeated so one row reads whole; `UNKNOWN` for an account activated but not yet judged, before its first posture is published — every figure of its row `null`, `headroomUnknownArm` `UNEVALUABLE`.
  - Allowed values: `UNKNOWN`, `NORMAL`, `HEDGE_ONLY`, `BLOCKED`
- `arm` (enum, required) — What set the posture, repeated from the posture row; `UNKNOWN` under `NORMAL`, and before the first posture is published.
  - Allowed values: `UNKNOWN`, `GROSS_LEVERAGE_NO_SPOT`, `NET_LEVERAGE_NO_SPOT`, `GROSS_LEVERAGE_WITH_SPOT`, `MARGIN_EQUITY_FLOOR`, `DATA_QUALITY`, `UNEVALUABLE`
- `pricedAtNs` (string, required, nullable) — When the record the figures derive from was priced, epoch nanoseconds as a decimal string; `null` before the account's first record.
- `nlvUsd` (string, required, nullable) — money (an exact decimal string at the scale the row holds it, trailing zeros included): The record's net liquidation value in USD, every wallet counted (`GET /risk/records`); `null` where the record states none.
- `marginEquityUsd` (string, required, nullable) — money (an exact decimal string at the scale the row holds it, trailing zeros included): The record's margin equity in USD — the margin wallets alone, what the leverage ratios divide by and the floor guards; 0 at a custodian, which margins nothing; `null` where the record states none.
- `marginHeadroomUsd` (string, required, nullable) — money (an exact decimal string at the scale the row holds it, trailing zeros included): What the margin wallets could shed and stay `NORMAL` against the record this row derives from, however the published ratio was rounded — rounded down, never below 0; the whole margin equity with no limit configured; 0 at a custodian. Sized for cash: a coin the margin wallets hold is exposure under a with-spot limit, so a shed in it moves that ratio too — move cash, or size coin against that limit. The live state may differ from the record. `null` where it cannot be derived — see `headroomUnknownArm`.
- `headroomUnknownArm` (enum, required, nullable) — Why the figures are `null` — the closed list: `DATA_QUALITY`, the record is partial; `UNEVALUABLE`, the account has no record yet, its record states no NLV or no margin equity, or — under a configured limit — its margin equity is at or below 0, the limit's ratio is absent or saturated (the record's ceiling for an equity a hair above zero beside a real exposure), the limit is one unit wide, or a figure exceeds what a 64-bit amount holds. `null` when the figures are known.
  - Allowed values: `DATA_QUALITY`, `UNEVALUABLE`
- `withdrawableUsd` (string, required, nullable) — money (an exact decimal string at the scale the row holds it, trailing zeros included): What the limits would let leave the account — a ceiling, not the venue's `available`: at an exchange the non-margin wallets (`nlvUsd − marginEquityUsd`, its funding wallet) plus `marginHeadroomUsd`; at a custodian the whole `nlvUsd` — a vault has no margin wallet, whatever margin equity its record states. What the venue lets out now is its `available`, and a transfer's own checks still apply. `null` when the headroom is. Its headroom share is sized for cash, as `marginHeadroomUsd` is.
- `shortfallUsd` (string, required, nullable) — money (an exact decimal string at the scale the row holds it, trailing zeros included): The top-up into the margin wallets that returns the account to `NORMAL` against this row's record — rounded up, so never 0 past a threshold; 0 with the record inside every limit, and at a custodian; `null` when the headroom is. The posture beside it may differ: judged on every recompute, the record published on a step. Sized for cash, as `marginHeadroomUsd` is: a top-up in a coin a with-spot limit counts raises that exposure too. From outside it arrives by the venue's route — at OKX via funding.
- `inFlightUsd` (string, required, nullable) — money (an exact decimal string at the scale the row holds it, trailing zeros included): What is on its way to this account and no custody total shows yet — each on-chain transfer to it from `IN_TRANSIT` until its destination first reports it, valued in USD at the read. `null` until the transfer routes exist.
- `unvalued` (list of integer, required) — Asset ids of in-flight amounts with no current USD rate, each contributing `null` to `inFlightUsd`, never 0; empty until the transfer routes exist.

### RiskCapitalTotal

A total of the capital view's rows under one key — a venue's name in `byVenue`, a location in `byLocation` — one population per total: each figure summed over the rows whose figures are known (`null` when none is), every row under the key counted and the rows whose figures are unknown counted beside that, feeding no sum.

- `key` (string, required) — The venue's name, or the location (`EXCHANGE`, `CUSTODIAN`).
- `accounts` (integer, required) — Every row under the key, the unknown ones included — `unknownAccounts` of them feed no sum.
- `unknownAccounts` (integer, required) — The rows whose figures are unknown (`headroomUnknownArm` set): counted here, and in no sum — every sum of this total, `nlvUsd` and `marginEquityUsd` included, runs over the other rows alone.
- `nlvUsd` (string, required, nullable) — money (an exact decimal string at the scale the row holds it, trailing zeros included): The summed `nlvUsd` over the rows whose figures are known.
- `marginEquityUsd` (string, required, nullable) — money (an exact decimal string at the scale the row holds it, trailing zeros included): The summed `marginEquityUsd` over the rows whose figures are known.
- `marginHeadroomUsd` (string, required, nullable) — money (an exact decimal string at the scale the row holds it, trailing zeros included): The summed `marginHeadroomUsd` over the rows whose figures are known.
- `withdrawableUsd` (string, required, nullable) — money (an exact decimal string at the scale the row holds it, trailing zeros included): The summed `withdrawableUsd` over the rows whose figures are known.
- `shortfallUsd` (string, required, nullable) — money (an exact decimal string at the scale the row holds it, trailing zeros included): The summed `shortfallUsd` over the rows whose figures are known.
- `inFlightUsd` (string, required, nullable) — money (an exact decimal string at the scale the row holds it, trailing zeros included): The summed `inFlightUsd`; `null` until the transfer routes exist.

### ErrorBody

What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.

- `code` (string, required) — The code to branch on — stable and open (before 1.0.0 a minor may remove one, its changelog naming it): treat one you do not know by its HTTP status. The gateway's: - 400: `MALFORMED_REQUEST`, `MISSING_IDEMPOTENCY_KEY`, `INVALID_IDEMPOTENCY_KEY`, `INVALID_IF_MATCH`, `INVALID_CURSOR` - 401: `UNAUTHENTICATED` - 403: `FORBIDDEN_PRINCIPAL`, `NOT_REGISTERED`, `INVITATION_EXPIRED`, `EMAIL_UNVERIFIED`, `ORG_NOT_ACTIVE`, `CAPABILITY_DENIED` - 404: `NOT_FOUND`, `UNKNOWN_OPERATION`, `ROUTE_NOT_FOUND` (no route answers the path) - 405: `METHOD_NOT_ALLOWED` - 409: `IDEMPOTENCY_KEY_REUSED`, `INTAKE_KEY_REUSED`, `KEY_ALREADY_REGISTERED`, `CONNECTION_DOWN` (`POST /transfers`), `EXCEEDS_MARGIN_HEADROOM`, `HEADROOM_UNKNOWN` (a transfer's submit and its approval) - 413: `TOO_LARGE`, `PAYLOAD_TOO_LARGE`, `DOCUMENT_TOO_LARGE` - 422: a reference this member will not send: `INSTRUMENT_NOT_LIVE`, `ACCOUNT_NOT_ACTIVE` (`POST /orders`), `REFERENCE_UNKNOWN_INSTRUMENT`, `REFERENCE_INSTRUMENT_NOT_LIVE`, `REFERENCE_UNKNOWN_ACCOUNT` (an algo document); `VENUE_UNSUPPORTED`, `DEDICATED_KEY`, `DESTINATION_NOT_ALLOWED` - 428: `PRECONDITION_REQUIRED` - 429: `INBOX_FULL`, `IN_FLIGHT_FULL`, `RATE_LIMITED` - 500: `INTERRUPTED`, `INTERNAL_ERROR`, `PROJECTION_MISS` - 503: `NOT_PRIMED`, `NOT_SERVING`, `OWNER_ABSENT`, `INTAKE_UNAVAILABLE`, `BALANCES_UNAVAILABLE`, `POSITIONS_UNAVAILABLE`, `RISK_UNAVAILABLE`, `TRANSFERS_UNAVAILABLE`, `ALGOS_UNAVAILABLE`, `NOTIFICATIONS_UNAVAILABLE`, `TICKETS_UNAVAILABLE`, `REGISTRATION_PENDING`, `PROJECTION_BEHIND`, `LOST`, `REJECTED_NOT_REGISTERED`, `REJECTED_NOT_ACTIVE` The record owners' refusals ride verbatim — `OrgRegisterRejected.reason`, `OrderRejected.reason`, `AlgoRejected.reason`, `RiskLimitRejectReason`, `RiskAdjustmentRejectReason`, `ManualExecutionRejectReason`, `TransferRejectReason` and `NotificationEndpointRejected.reason` list them; the guide maps each to its status.
- `message` (string, required) — For display only; its wording may change at any time.
- `requestId` (string, required) — The request's id, also sent as X-Request-Id; quote it to support.
- `retryable` (boolean, required) — Whether sending the identical request again, its `Idempotency-Key` included, after `Retry-After` or a short pause, can succeed with nothing else changed. `false` where something must change first: the request, its key, its precondition, the caller's standing, or the platform's own records or deployment. A refusal the record owner judged is always `false`: it is the recorded answer to its key, which replays it.

## Examples

**Response**

```json
{
  "globalSequence": "250106",
  "accounts": [
    {
      "accountId": 118301490,
      "venue": "okx",
      "location": "EXCHANGE",
      "posture": "NORMAL",
      "arm": "UNKNOWN",
      "pricedAtNs": "1791553890016000000",
      "nlvUsd": "1000000.00000000",
      "marginEquityUsd": "600000.00000000",
      "marginHeadroomUsd": "224999.99756249",
      "headroomUnknownArm": null,
      "withdrawableUsd": "624999.99756249",
      "shortfallUsd": "0.00000000",
      "inFlightUsd": null,
      "unvalued": [
        1
      ]
    },
    {
      "accountId": 118301482,
      "venue": "anchorage",
      "location": "CUSTODIAN",
      "posture": "NORMAL",
      "arm": "UNKNOWN",
      "pricedAtNs": "1791553890016000000",
      "nlvUsd": "250000.00000000",
      "marginEquityUsd": "0.00000000",
      "marginHeadroomUsd": "0.00000000",
      "headroomUnknownArm": null,
      "withdrawableUsd": "250000.00000000",
      "shortfallUsd": "0.00000000",
      "inFlightUsd": null,
      "unvalued": [
        1
      ]
    }
  ],
  "byVenue": [
    {
      "key": "anchorage",
      "accounts": 1,
      "unknownAccounts": 0,
      "nlvUsd": "250000.00000000",
      "marginEquityUsd": "0.00000000",
      "marginHeadroomUsd": "0.00000000",
      "withdrawableUsd": "250000.00000000",
      "shortfallUsd": "0.00000000",
      "inFlightUsd": null
    },
    {
      "key": "okx",
      "accounts": 1,
      "unknownAccounts": 0,
      "nlvUsd": "1000000.00000000",
      "marginEquityUsd": "600000.00000000",
      "marginHeadroomUsd": "224999.99756249",
      "withdrawableUsd": "624999.99756249",
      "shortfallUsd": "0.00000000",
      "inFlightUsd": null
    }
  ],
  "byLocation": [
    {
      "key": "CUSTODIAN",
      "accounts": 1,
      "unknownAccounts": 0,
      "nlvUsd": "250000.00000000",
      "marginEquityUsd": "0.00000000",
      "marginHeadroomUsd": "0.00000000",
      "withdrawableUsd": "250000.00000000",
      "shortfallUsd": "0.00000000",
      "inFlightUsd": null
    },
    {
      "key": "EXCHANGE",
      "accounts": 1,
      "unknownAccounts": 0,
      "nlvUsd": "1000000.00000000",
      "marginEquityUsd": "600000.00000000",
      "marginHeadroomUsd": "224999.99756249",
      "withdrawableUsd": "624999.99756249",
      "shortfallUsd": "0.00000000",
      "inFlightUsd": null
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.example.com/risk/capital"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.example.com/risk/capital';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

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

func main() {

	url := "https://api.example.com/risk/capital"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.example.com/risk/capital")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.example.com/risk/capital")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.example.com/risk/capital', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.example.com/risk/capital");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/risk/capital")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```