ProviderGateMismatch or DepositorGateRequired, and the API refuses the same cases first.
An allocation, a draw cap or a rebalance for a MARKET-priced market is also refused until the market’s borrower register qualifies as a professional gate. See Professional borrowers.
A register can be the eligibility register of a verification profile, so a vault can take deposits only from the customers admitted under one profile. When creating the vault in the Issuer Portal, the operator can name such a profile instead of a register address. The register can also be a whitelist the operator’s instance keeps, owns or manages. A whitelist examines no identity, so it gates depositors only once the operator attests that it lists identified wallets only. See Whitelists as Gates. Vault reads name the profile in depositorProfile and the whitelist in depositorAccessList. On a vault without a register of its own they name the adopted register the same way, and depositorGate.kind reads ADOPTED.
A vault keeps its register for life. On Sepolia, a vault gated on the previous Trusset ID Register, 0xE9114c40934f6fB6BB317935156b731f7A86D006, refuses every depositor verified since 10 October 2026, because that register takes no new identities. Its reads carry depositorRegisterRetired: true, a deposit for such a wallet is refused with 409 IDENTITY_GATE_RETIRED, and its holders redeem as before. A new vault or vault group cannot be created on that register. See The Previous Trusset ID Register.
Trusset holds no role on any vault. Each vault belongs to the issuer operating it, and every vault record names that operator in operatedBy. Show the operator wherever you show the vault.
This API covers depositing, redeeming, reading positions, and paying out the distributor fees a vault earns. Creating a vault or a vault group, allocating into markets, setting a market’s draw cap, pausing and resuming deposits, lowering the fee, publishing, and managing the vault’s roles are operator actions done in the Issuer Portal. Get Vault reads the roles of your own vault, and Vault Roles describes them.
Banks create and run vaults: see Fund the market. Fintechs bring depositors and earn the distributor share once the vault’s operator approves them: see Offer earn.
Vault groups
A vault group is one vault product with two to four currency pockets. Each pocket is a vault that holds one settlement token (stablecoin), and the pockets are published together under one risk disclosure. A deposit stays in the currency of its pocket: nothing converts between pockets. Get Vault Group reads a group with its totals per currency, and Deposit to Vault Group deposits into the pocket of the currency you name. Every other vault endpoint works on a pocket by its vault ID. A depositor register is optional for a group, as for a single vault. A group created with one (a verification profile’s eligibility register, a register address, or a whitelist) examines the depositors of every pocket against it for the life of the group. A group created without one namesnull as its identityRegistryAddress, and each pocket then works like a single vault without a register: it adopts the provider register of the first market it funds and keeps it for good. The pockets adopt independently, so two pockets can end up on different registers when their markets name different ones. Each pocket names its gate in depositorGate. The codes the group endpoints answer are listed under Error codes.
Base Path
X-API-Key header. See Authentication. The instance bound to your key determines which vaults you see. You see your own vaults and every vault published on the same network and environment. You also see any unpublished vault in which your instance is a distributor of record. An instance runs at most three live vault products, and a vault group counts as one. A deposit into another operator’s unpublished vault is refused with VAULT_NOT_PUBLISHED, and redemptions from it stay open.
A lending market builds deposits into and redemptions from the vaults connected to it as well. See Deposit to Vault and Redeem from Vault, which confirm on their own endpoint.
Reads carry a limit of 100 requests per minute and writes one of 10 per minute. Each is counted per API key across every endpoint that carries it, inside the ceiling of 200 per minute per key. See Rate Limits.
Distributor attribution
The instance whose API key builds a depositor’s first attributed deposit becomes that depositor’s distributor. The deposit names the instance’s primary verified wallet, and the vault binds the depositor to it once and never rebinds. Every share the holder has or later receives is attributed to that distributor. A deposit can bind a new holder only to the vault owner or to a distributor the operator approved. When your instance’s wallet is not approved, the API names no distributor and the deposit still goes through. Theattribution block on Deposit says which case applies before the depositor signs.
Each market sets aside a distributor share: 5 percent of repaid interest after Trusset’s 20 percent infrastructure fee, and 5 percent of each fixed transaction fee. The vault’s slice reaches it through Collect Distributor Fees, one market at a time. The part earned by attributed shares goes to their distributors through Pay Distributor, and the rest to the vault’s fee recipient, the admin by default, through Pay Operator Fees. Any wallet may send all three, and each pays a fixed destination, never the signer. Trusset holds none of it.
Redemptions
An operator can pause deposits. Nothing can pause a redemption. When market utilization blocks part of the vault’s value, a redemption pays out what liquidity allows and the remaining shares stay in the wallet. No register examines a redemption, and the payout goes to the wallet that signs. See Redeem. Size a redemption againstredeemableNow on Get Vault, not against idleAssets. Idle funds are only the part the vault holds loose. redeemableNow adds, for each market the vault funds, whichever is smaller: what the vault holds there, and what that market has uncommitted. Redeem answers the same question for one specific redemption, with willFillFully and expectedPayout.
When a deposit is refused and a redemption is not
The asymmetry is deliberate. A deposit issues shares at a price, so it must not happen against a number the vault cannot stand behind. A redemption returns a holder’s own money, so nothing on that path may close the door. A market the vault funds can go dark. When that happens the vault cannot total its book, and deposits are refused withVAULT_BOOK_INCOMPLETE until it answers again or the operator writes it off. Redemptions carry on, quoted from totals read without the completeness flag. The price they get understates the vault by an unknown amount, priceWarning says so, and the difference stays with the holders who wait.
A vault can also end up with shares in issue against nothing. Deposits into it are refused with VAULT_WIPED_OUT, because they would be absorbed by the existing holders rather than buying a position. Such a vault cannot be recapitalized and the operator has to run a new one.
These refusals read the vault’s live state. When that read fails, the API still returns calldata, and the vault contract refuses the same cases on-chain.
Two more refusals are the API’s own, and the contract does not make them. A market the vault funds can carry an open loan below the liquidation threshold, or seized debt still waiting for its sale, while the share price counts that debt at full value. Deposits are then refused with VAULT_MARKET_IMPAIRED until those loans are settled, and a redemption built with Redeem carries impairmentWarning. A vault that wrote off a market that answers again and still holds its pool shares refuses deposits with VAULT_RECOVERY_PENDING until the operator pulls that value back, so a recovery reaches the holders who bore the write-off. Get Vault shows both in onChain.impairment.
Failed reads
The chain state on Get Vault carries areadFailed flag. When it is true the figures are absent, not zero. Keep your last verified values on screen and retry. A vault whose read failed still holds every deposit it held a minute ago.
A chain or database outage answers 503 with CHAIN_UNAVAILABLE or SERVICE_UNAVAILABLE. Both are retryable.
Response envelope
success is false, data is null, and error carries code and message. Schema failures use VALIDATION_ERROR, and most carry error.details listing each offending field. metadata.requestId always equals the X-Request-Id response header, so you can quote it when reporting a problem. Always branch on success rather than on the HTTP status alone.
Writes
Every write endpoint returns unsigned transaction data for a wallet you control to sign and broadcast. Nothing is submitted on your behalf. A response with one transaction carries it intransaction. A response with several carries action: "SIGN_TRANSACTIONS" and an ordered steps array, each step { action, transaction, functionName, description }. Each unsigned transaction carries value: "0" and the chainId your instance resolves to.
A market the vault funded can write off distributor accrual with a defaulted loan. Until the vault records that loss, a deposit, a distributor fee collection or payout, and an operator fee payout each start with one recordMarketLoss step per such market. recordsWriteOffs lists them and writeOffNote explains them. Sign every step in order, and confirm with the hash of the step at confirmStepIndex, the last one.
Report a deposit or redemption hash to Confirm Transaction. The distributor fee writes confirm on their own route instead: send the same request again with { "txHash": "0x..." }, as each response’s confirmWith names. Either way, the backend verifies the receipt on-chain before recording anything.