---
title: "Get user vault state and active positions"
method: GET
path: "/v1/vault"
tags: ["Vault"]
---

# Get user vault state and active positions

`GET /v1/vault`

Returns the user's vault balance and active positions. Returns data: null
(200 OK) if the user has no vault yet (vault is created on first trade).

## Response `200`

OK — vault state or null if no vault exists

- object
  - `data` UserVaultResponse — Vault state with active position summaries (GET /v1/vault response). Returns the caller's bettor-side vault (owner_type='user') when one exists; falls back to their maker-side vault (owner_type='mm') for pure-MM accounts so the portfolio surface reflects every USDC the caller controls. `positions` is the bettor-side active list when returning the user vault, or the maker-side active list (joined via `q.market_maker_id`) when returning the MM vault.
    - `vault_pda` string
    - `vault_token_account` string
    - `gross_balance` number
    - `locked_collateral` number
    - `free_balance` number
    - `positions` VaultPositionSummary[]
      - `position_id` string — 16-byte position ID (hex encoded)
      - `rfq_id` string, uuid
      - `user_stake` number — Bettor side of the trade. The caller's stake on the bettor-side vault response; the counterparty's stake on the maker-side vault response.
      - `mm_risk` number — Maker side of the trade. The counterparty's collateral on the bettor-side vault response; the caller's own collateral on the maker-side vault response.
      - `total_payout` number
      - `status` 'pending' | 'processing' | 'active' | 'settling' | 'cancelling' | 'settled_win' | 'settled_loss' | 'cancelled' | 'reconciling_mm_release' | 'expired_pending_mm_release' | 'expired' | 'reconciling_bought_back_db' | 'bought_back_pending_db' | 'bought_back' | 'error' — Vault position lifecycle. `pending`/`processing` are intermediate states before on-chain creation; `settling`/`cancelling` are intermediate states for settlement/cancellation; `settled_win`/`settled_loss`/`cancelled` are terminal; the `*_mm_release` and `expired` states cover the permissionless-expiry path; the buyback path is `active → bought_back_pending_db → bought_back` (with `reconciling_bought_back_db` as the short-lived reconciler sentinel); `error` means retries are exhausted and manual intervention is required.
      - `created_at` string, date-time

---

[API](https://skmtc.net/totalistrading/apis/totalis-rfq-api.md) · [All operations](https://skmtc.net/totalistrading/apis/totalis-rfq-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/totalistrading/totalis-rfq-api/revisions/b0adb9a590b4/schema)