---
title: "Receive cap, trust level and hold window"
method: GET
path: "/api/vault/status"
tags: ["pay"]
---

# Receive cap, trust level and hold window

`GET /api/vault/status`

## Request

- Base URL: `https://api.depixapp.com`
- URL: `https://api.depixapp.com/api/vault/status`
- Auth: HTTP bearer

What the account may receive, how long a new deposit will be held, and what it still needs for the next level — read this BEFORE creating a charge so the amount is never refused and the hold is never a surprise. A deposit that would break the cap answers HTTP 400 `account_limit_exceeded` with the same numbers in `error.details`. The cap and the hold are independent: `vault_window_hours: 0` with `cap.enforced: true` means charges are refused above the cap and nothing is held below it. Deliberately omits which risk rule fired and every threshold: a caller learns that a limit exists, never the map around it.

## Response `200`

Current position in the hold policy.

- VaultStatusResponse: Receive cap, trust level, hold window and what the account still needs for the next level. Same payload for a human JWT and an agent API key — the economics never fork by account type.
  - `vault_active` boolean, required: false when the whole mechanism is switched off — every number below is then informational only and deposits settle on the pre-Cofre rules. true does NOT by itself mean deposits are held: the receive cap and the hold window are independent switches, and `vault_window_hours` is the one that says whether this account waits.
  - `policy_version` string, required: Version of the policy that produced these numbers. Every deposit records the version that decided its own deadline.
  - `level` object, required: Trust level (0-4). Drives the cap and the hold window; it does NOT unlock the merchant tools.
    - `current` integer, required: Level in force right now.
    - `max` integer, required: Highest level the ladder defines.
    - `pinned` boolean, required: true when support fixed the level by hand; the automatic evaluation then leaves it alone.
    - `frozen_until` string, nullable, required: Timestamp until which the level cannot rise automatically; null when it is not frozen. Expires on its own.
    - `eligible` integer, required: Level the automatic ladder would grant today — differs from `current` only while the level is pinned.
  - `cap` object, required: How much the account may RECEIVE inside the rolling window.
    - `enforced` boolean, required: false when the cap is not being applied; nothing is refused in that state.
    - `cents` integer, required: The cap, in cents, for the current window.
    - `used_cents` integer, required: Already received inside the window. Includes recent unpaid QRs, so creating charges without paying them does not free up room.
    - `available_cents` integer, required: cents - used_cents, floored at zero.
    - `window_days` integer, required: Length of the rolling window in days.
    - `resets_at` string, nullable, required: When the OLDEST counted deposit leaves the window, i.e. when part of the cap frees up. null when nothing is counted. The window rolls; it is not a calendar reset.
    - `pinned` boolean, required: true when the cap was set by hand (support/KYC) instead of coming from the level.
    - `first_deposit_pending` boolean, required: true while the account has no PERSONAL deposit past `pending`. This is a rung BELOW `cents`: until it clears, a deposit is refused above the first-deposit ceiling whatever the cap says (400 account_limit_exceeded with limit "first_deposit"), so a client must not quote `available_cents` as spendable while it is true. Counted exactly as POST /api/deposit counts it — personal deposits only, post-payment statuses — and NOT keyed on verification: the rung is about history.
  - `vault_window_hours` integer, required: Hours a new deposit will wait before converting, at the current level. **0 means no hold is added** — either the whole mechanism is off, or the hold window is off while the receive cap keeps being enforced (`vault_active: true` with `cap.enforced: true`). Read this field, not `vault_active`, before telling anyone their money will wait. It never reports the pre-existing per-account delays, which are outside this mechanism.
  - `instant` object, required: The only irreversible path: money that settles immediately. Bounded per transaction AND per window.
    - `enabled` boolean, required: false when instant settlement is switched off; everything then goes through the hold.
    - `max_per_tx_cents` integer, required: Above this amount a deposit NEVER settles instantly, whatever the cap says.
    - `cap_cents` integer, required: Ceiling on the total settled instantly inside the window.
    - `used_cents` integer, required: Already settled instantly inside the window.
    - `window_days` integer, required: Length of the instant-settlement window in days.
    - `graduation_completed` boolean, required: true once enough deposits have settled for instant settlement to be available.
    - `deposits_settled` integer, required: Settled deposits counted toward that requirement.
    - `deposits_required` integer, required: Settled deposits the requirement asks for.
    - `identity_ok` boolean, required: true when the account cleared its identity requirement (verified WhatsApp for a human, being an agent for an agent).
    - `graduation_hold_hours` integer, nullable, required: EXACT hours a deposit settling under the graduation waits (deposits 2 to `deposits_required`, at or below `graduation_per_tx_cents`) — for this account, today. Reflects a manual per-account delay when support set one, so it can exceed the default; never quote the default instead of this field. Null when the graduation mechanism is off: then no exact figure exists and `vault_window_hours` is the honest upper bound. This is what lets a client warn "1 dia" for the second sale of a new account instead of rounding up to the level window.
    - `graduation_per_tx_cents` integer, nullable, required: Per-deposit ceiling under which the graduation wait above applies. A graduating deposit ABOVE it takes the level's `vault_window_hours` instead. Null when the graduation mechanism is off.
    - `graduation_first_max_cents` integer, nullable, required: Ceiling of the very FIRST deposit (deposits_settled = 0), which settles instantly at or below it — above it, a personal deposit is refused by the first-deposit rung (see `cap.first_deposit_pending`), so no hold happens on a first deposit either way. Null when the graduation mechanism is off.
  - `progress` object, required: Inputs of the automatic ladder, and the gap to the next rung.
    - `account_age_days` integer, required: Days since the account was created.
    - `matured_volume_cents` integer, required: Received volume that has already matured and counts toward the next level. Counts from the moment the PIX was PAID, not from the conversion.
    - `next_level` object, nullable, required: The next rung and what is still missing.
      - `level` integer, required: The next level.
      - `cap_cents` integer, nullable, required: The receive cap that level grants, in cents — what the requirements below buy. Null only if the ladder is misconfigured.
      - `window_hours` integer, nullable, required: How long a deposit waits at that level, in hours — the other half of what the requirements below buy, since climbing both raises the cap and shortens the wait. Unlike the top-level `vault_window_hours`, this is the LADDER's number and is reported whether or not the hold window is currently in force: it describes a rung, not the money arriving now. A client must therefore never render it as a wait that applies today. Null only if the ladder is misconfigured.
      - `min_age_days` integer, required: Minimum account age it asks for.
      - `min_volume_cents` integer, required: Minimum matured volume it asks for.
      - `current_age_days` integer, required: Current account age in days.
      - `current_volume_cents` integer, required: Current matured volume in cents.
      - `missing_age_days` integer, required: Days still missing, zero when satisfied.
      - `missing_volume_cents` integer, required: Cents of matured volume still missing, zero when satisfied.
  - `merchant_tools` object, required: A SEPARATE axis from the level: it unlocks checkouts and products, and never changes the cap or the window.
    - `verified` boolean, required: true when the account may create checkouts and products.
  - `kyc` object, required: The path to a higher cap, available at every level. Always a human action — an agent passes the link to its operator.
    - `available` boolean, required: true when the higher-cap path is open.
    - `booking_url` string, nullable, required: Where to book the verification call; null when unavailable.

## Other responses

- `401`: Missing or invalid credentials.
- `403`: Account suspended.
- `404`: Account not found.
- `429`: Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).

---

[API](https://skmtc.dev/depixapp/apis/depix-api.md) · [All operations](https://skmtc.dev/depixapp/apis/depix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/depixapp/apis/depix-api/revisions/04094536dd0f?raw)