VaultStatusResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/depixapp-com/json-schema/depixapp-com-vault-status-response-schema.json",
  "title": "VaultStatusResponse",
  "description": "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.",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/depixapp-com-openapi.yml#/components/schemas/VaultStatusResponse",
  "type": "object",
  "required": [
    "vault_active",
    "policy_version",
    "level",
    "cap",
    "vault_window_hours",
    "instant",
    "progress",
    "merchant_tools",
    "kyc"
  ],
  "additionalProperties": false,
  "properties": {
    "vault_active": {
      "type": "boolean",
      "description": "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": {
      "type": "string",
      "description": "Version of the policy that produced these numbers. Every deposit records the version that decided its own deadline."
    },
    "level": {
      "type": "object",
      "description": "Trust level (0-4). Drives the cap and the hold window; it does NOT unlock the merchant tools.",
      "required": [
        "current",
        "max",
        "pinned",
        "frozen_until",
        "eligible"
      ],
      "additionalProperties": false,
      "properties": {
        "current": {
          "type": "integer",
          "description": "Level in force right now."
        },
        "max": {
          "type": "integer",
          "description": "Highest level the ladder defines."
        },
        "pinned": {
          "type": "boolean",
          "description": "true when support fixed the level by hand; the automatic evaluation then leaves it alone."
        },
        "frozen_until": {
          "type": [
            "string",
            "null"
          ],
          "description": "Timestamp until which the level cannot rise automatically; null when it is not frozen. Expires on its own."
        },
        "eligible": {
          "type": "integer",
          "description": "Level the automatic ladder would grant today — differs from `current` only while the level is pinned."
        }
      }
    },
    "cap": {
      "type": "object",
      "description": "How much the account may RECEIVE inside the rolling window.",
      "required": [
        "enforced",
        "cents",
        "used_cents",
        "available_cents",
        "window_days",
        "resets_at",
        "pinned",
        "first_deposit_pending"
      ],
      "additionalProperties": false,
      "properties": {
        "enforced": {
          "type": "boolean",
          "description": "false when the cap is not being applied; nothing is refused in that state."
        },
        "cents": {
          "type": "integer",
          "description": "The cap, in cents, for the current window."
        },
        "used_cents": {
          "type": "integer",
          "description": "Already received inside the window. Includes recent unpaid QRs, so creating charges without paying them does not free up room."
        },
        "available_cents": {
          "type": "integer",
          "description": "cents - used_cents, floored at zero."
        },
        "window_days": {
          "type": "integer",
          "description": "Length of the rolling window in days."
        },
        "resets_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "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": {
          "type": "boolean",
          "description": "true when the cap was set by hand (support/KYC) instead of coming from the level."
        },
        "first_deposit_pending": {
          "type": "boolean",
          "description": "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": {
      "type": "integer",
      "description": "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": {
      "type": "object",
      "description": "The only irreversible path: money that settles immediately. Bounded per transaction AND per window.",
      "required": [
        "enabled",
        "max_per_tx_cents",
        "cap_cents",
        "used_cents",
        "window_days",
        "graduation_completed",
        "deposits_settled",
        "deposits_required",
        "identity_ok",
        "graduation_hold_hours",
        "graduation_per_tx_cents",
        "graduation_first_max_cents"
      ],
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "false when instant settlement is switched off; everything then goes through the hold."
        },
        "max_per_tx_cents": {
          "type": "integer",
          "description": "Above this amount a deposit NEVER settles instantly, whatever the cap says."
        },
        "cap_cents": {
          "type": "integer",
          "description": "Ceiling on the total settled instantly inside the window."
        },
        "used_cents": {
          "type": "integer",
          "description": "Already settled instantly inside the window."
        },
        "window_days": {
          "type": "integer",
          "description": "Length of the instant-settlement window in days."
        },
        "graduation_completed": {
          "type": "boolean",
          "description": "true once enough deposits have settled for instant settlement to be available."
        },
        "deposits_settled": {
          "type": "integer",
          "description": "Settled deposits counted toward that requirement."
        },
        "deposits_required": {
          "type": "integer",
          "description": "Settled deposits the requirement asks for."
        },
        "identity_ok": {
          "type": "boolean",
          "description": "true when the account cleared its identity requirement (verified WhatsApp for a human, being an agent for an agent)."
        },
        "graduation_hold_hours": {
          "type": [
            "integer",
            "null"
          ],
          "description": "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": {
          "type": [
            "integer",
            "null"
          ],
          "description": "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": {
          "type": [
            "integer",
            "null"
          ],
          "description": "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": {
      "type": "object",
      "description": "Inputs of the automatic ladder, and the gap to the next rung.",
      "required": [
        "account_age_days",
        "matured_volume_cents",
        "next_level"
      ],
      "additionalProperties": false,
      "properties": {
        "account_age_days": {
          "type": "integer",
          "description": "Days since the account was created."
        },
        "matured_volume_cents": {
          "type": "integer",
          "description": "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": {
          "description": "Requirements for the next level, or null at the top of the ladder.",
          "oneOf": [
            {
              "type": "object",
              "description": "The next rung and what is still missing.",
              "required": [
                "level",
                "cap_cents",
                "window_hours",
                "min_age_days",
                "min_volume_cents",
                "current_age_days",
                "current_volume_cents",
                "missing_age_days",
                "missing_volume_cents"
              ],
              "additionalProperties": false,
              "properties": {
                "level": {
                  "type": "integer",
                  "description": "The next level."
                },
                "cap_cents": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "The receive cap that level grants, in cents — what the requirements below buy. Null only if the ladder is misconfigured."
                },
                "window_hours": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "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": {
                  "type": "integer",
                  "description": "Minimum account age it asks for."
                },
                "min_volume_cents": {
                  "type": "integer",
                  "description": "Minimum matured volume it asks for."
                },
                "current_age_days": {
                  "type": "integer",
                  "description": "Current account age in days."
                },
                "current_volume_cents": {
                  "type": "integer",
                  "description": "Current matured volume in cents."
                },
                "missing_age_days": {
                  "type": "integer",
                  "description": "Days still missing, zero when satisfied."
                },
                "missing_volume_cents": {
                  "type": "integer",
                  "description": "Cents of matured volume still missing, zero when satisfied."
                }
              }
            },
            {
              "type": "null",
              "description": "Already at the top of the ladder."
            }
          ]
        }
      }
    },
    "merchant_tools": {
      "type": "object",
      "description": "A SEPARATE axis from the level: it unlocks checkouts and products, and never changes the cap or the window.",
      "required": [
        "verified"
      ],
      "additionalProperties": false,
      "properties": {
        "verified": {
          "type": "boolean",
          "description": "true when the account may create checkouts and products."
        }
      }
    },
    "kyc": {
      "type": "object",
      "description": "The path to a higher cap, available at every level. Always a human action — an agent passes the link to its operator.",
      "required": [
        "available",
        "booking_url"
      ],
      "additionalProperties": false,
      "properties": {
        "available": {
          "type": "boolean",
          "description": "true when the higher-cap path is open."
        },
        "booking_url": {
          "type": [
            "string",
            "null"
          ],
          "description": "Where to book the verification call; null when unavailable."
        }
      }
    }
  }
}