Queries
Get Vault
Full vault record plus live chain state and an optional holder position
GET
/
lending-external-securities-v2
/
api
/
vaults
/
{vaultId}
curl "https://api.trusset.org/lending-external-securities-v2/api/vaults/cmssh8t2u0003cghxkx1w1fwd?address=0x6a6cba16dad34f7ea7ecbcdbf050f8146b942d6b" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/lending-external-securities-v2/api/vaults/${vaultId}?address=${wallet}`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
if (!data.onChain || data.onChain.readFailed) {
scheduleRetry();
} else {
console.log(`share price ${data.onChain.sharePrice}, ${data.onChain.idleAssets} ${data.assetSymbol} idle`);
}
{
"success": true,
"data": {
"id": "cmssh8t2u0003cghxkx1w1fwd",
"own": false,
"vaultAddress": "0x4d0cfe39a3431b145d1a1393d901a36d459a1b13",
"assetAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
"assetSymbol": "USDC",
"assetDecimals": 6,
"identityRegistryAddress": "0xe9114c40934f6fb6bb317935156b731f7a86d006",
"depositorGate": {
"kind": "REGISTER",
"register": "0xe9114c40934f6fb6bb317935156b731f7a86d006",
"statement": "Deposits and share transfers are examined against this register."
},
"name": "Trusset Prime Demo Vault",
"symbol": "TPV",
"performanceFeeBps": 500,
"active": true,
"riskDisclosure": "Deposits fund overcollateralized lending markets.",
"riskDisclosureUrl": "https://bank.example/vault-risk",
"operatedBy": { "instanceName": "Trusset Client Demo", "issuerName": "Trusset UG", "isBank": true },
"onChain": {
"isOnChain": true,
"readFailed": false,
"vaultAddress": "0x4d0cfe39a3431b145d1a1393d901a36d459a1b13",
"owner": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
"asset": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
"identityRegistry": "0xe9114c40934f6fb6bb317935156b731f7a86d006",
"totalAssets": "126250.0",
"totalAssetsRaw": "126250000000",
"totalShares": "124691.358024",
"totalSharesRaw": "124691358024",
"sharePrice": "1.012500000005613861",
"idleAssets": "25000.0",
"allocatedAssets": "101250.0",
"redeemableNow": "87500.0",
"redeemableNowRaw": "87500000000",
"depositsPaused": false,
"performanceFeeBps": 500,
"blockTimestamp": 1786700400,
"assetsFullyReadable": true,
"supportsNotice": true,
"feeNotice": { "supported": true, "activatesAt": null, "delaySeconds": 604800, "ready": false },
"worstCaseHorizon": {
"horizon": "1794472800",
"bounded": true,
"complete": true,
"applies": true,
"basis": "OPEN_LOANS"
},
"allocations": [
{
"marketAddress": "0xae10e07a899526e97be3940ca6ee03af28394495",
"marketName": "Trusset Security Token",
"marketSymbol": "TRST",
"marketImageUri": null,
"lpShares": "100000000000",
"lpValue": "101250.0",
"lpValueRaw": "101250000000",
"deposited": "100000.0",
"marketAvailable": "62500.0",
"marketAvailableRaw": "62500000000",
"utilizationBps": 5503,
"borrowRateBps": 750,
"supplyRateBps": 309,
"curveBorrowRateBps": 750,
"fixedStampRateBps": null,
"drawCap": "0",
"drawCapFormatted": "0.0",
"evictionActivatesAt": null,
"exitHorizon": { "horizon": "1794472800", "bounded": true, "applies": true, "basis": "OPEN_LOANS" }
}
],
"interest": {
"readFailed": false,
"grossAnnual": "3128.625",
"netAnnual": "2972.19375",
"blendedGrossApyBps": 247.81,
"blendedNetApyBps": 235.42,
"performanceFeeBps": 500
}
},
"holder": {
"holderAddress": "0x6a6cba16dad34f7ea7ecbcdbf050f8146b942d6b",
"shares": "1000.0",
"sharesRaw": "1000000000",
"value": "1012.5",
"readFailed": false
},
"implementation": null,
"jitLiquidity": null
}
}
{
"success": true,
"data": {
"id": "cmssh8t2u0003cghxkx1w1fwd",
"name": "Trusset Prime Demo Vault",
"onChain": { "readFailed": true, "isOnChain": null },
"holder": null,
"implementation": null,
"jitLiquidity": null
}
}
{
"success": false,
"data": null,
"error": {
"code": "VAULT_NOT_FOUND",
"message": "Vault not found"
}
}
Returns the vault record with its live state.
onChain is the vault read from the chain in one aggregate. holder is the position of the wallet named in address, or null without one. On a vault your instance operates, implementation and jitLiquidity add the operator’s view; on every other vault both are null.
The record fields are those of a List Vaults row, depositorGate and distributorView included. A vault is visible here under the same rules as on that list.
Path Parameters
string
required
Vault ID from List Vaults.
Query Parameters
string
Wallet to read a position for. When it is a
0x address, holder carries that wallet’s shares and their current value. Any other value is ignored and holder is null.Response Fields
object
Show child attributes
Show child attributes
object
null for a vault with no recorded address.Show child attributes
Show child attributes
boolean
True when the chain could not be read. Every other field in this block is then absent, apart from
isOnChain and, when they could still be established, supportsNotice and feeNotice. Keep your last verified values instead of rendering zeros.boolean
true on a clean read, null when the read failed.string
The vault contract, lowercased.
string
The wallet that owns the vault on-chain. Only it can sign the vault’s owner-only actions, distributor approvals included.
string
The vault’s asset, read from the contract rather than from the record.
string
The vault’s own identity register, read from the contract.
null when the vault names none.string
Everything the vault is worth: idle funds plus its position in every allocated market. Formatted at the vault’s asset decimals.
string
The same figure in base units.
string
Shares in issue.
string
The same figure in base units.
string
Value of one share in the vault’s asset, as an 18-decimal string.
"1.0" is par. It rises as the funded markets pay interest.string
Funds not allocated to any market.
string
Total assets minus idle assets: funds working in the operator’s lending markets.
string
What a redemption could pay out at this moment. It is idle funds plus, for each allocated market, the smaller of two figures: the vault’s position there, and what that market has uncommitted.
null when any leg or the idle balance could not be read. Size a redemption against this, not against idleAssets.string
The same figure in base units.
boolean
True while the operator has paused deposits. Redemptions cannot be paused.
null when unreadable, which is not the same as unpaused.integer
Live fee. The contract only accepts decreases.
integer
Unix time of the block these figures were read in.
boolean
false when the vault’s position in at least one allocated market could not be read, so totalAssets understates the vault. Deposits are then refused with VAULT_BOOK_INCOMPLETE, and redemptions are quoted low.boolean
Whether this vault runs the implementation that announces its changes in advance and can write a dead market off.
null when that could not be established.object
The performance-fee notice. Collecting the fee mints shares to the operator and dilutes holders. The current implementation takes it only after an announced notice period.
Show child attributes
Show child attributes
boolean
true when the vault requires the notice, false on the earlier implementation that collects without one, null when unknown.integer
Unix time from which an announced collection may be taken.
null when none is announced. A holder who disagrees with the collection can redeem before it.integer
The notice period the vault applies.
boolean
Whether a collection could be taken now. Always
true on a vault without the notice.object
The vault’s disclosed exit ceiling,
null on a vault that does not expose it. Show it as the latest date a withdrawal may wait for, never as instant liquidity.Show child attributes
Show child attributes
string
Unix time, in seconds. It marks the latest moment a loan in any funded market can still be outstanding, grace period included.
null when no market ever stamped a term.boolean
false when at least one funded market carries a loan without a term, so no bounded horizon exists.boolean
false when a funded market could not be read. The horizon then understates.boolean
true when the horizon is bounded, set, and at least one funded market has money lent out. The contract keeps the latest due date it ever stamped, so a horizon that does not apply describes loans already gone.string
OPEN_LOANS when the horizon was narrowed to the due dates of the loans actually open. Absent when it is the contract’s own figure.array
One leg per allocated market, empty when nothing is allocated.
Show child attributes
Show child attributes
string
The lending market.
string
Name of the collateral the market lends against.
null when the market is not on record.string
Symbol of that collateral.
string
The collateral token’s image, as the market’s own instance uploaded it.
null when none.string
The vault’s liquidity-provider shares in the market, in base units.
string
What those shares are worth, in the vault’s asset. This is what the vault counts toward
totalAssets.string
The same figure in base units.
string
What the vault deposited into the market, as the market records it.
string
What the market has uncommitted, which bounds how much the vault can draw back now.
string
The same figure in base units.
integer
The market’s utilization.
null when its metrics could not be read.integer
The borrow rate that applies, a stamped fixed rate where the market’s interest model sets one. These are the rates shown on that market’s own page.
number
The rate liquidity providers earn there, after the fee split.
integer
The rate the interest curve alone gives.
integer
The fixed rate the market’s interest model stamps, or
null when it stamps none.string
The vault’s just-in-time draw cap for this market, in base units.
"0" means the vault has not consented to draws there. null when unreadable.string
The same cap formatted at the asset’s decimals.
integer
Unix time from which the operator may write this market off, when a write-off notice is running.
null when none is.object
This market’s own
horizon, bounded and applies, plus basis (OPEN_LOANS or HIGH_WATER_MARK) when it applies. null when unreadable. The vault-wide figure is worstCaseHorizon.boolean
Present and
true when the vault’s position in this market could not be read. This is the failure that makes assetsFullyReadable false.boolean
Present and
true when the position or the market’s metrics could not be read. A metrics failure costs the rates only.object
Show child attributes
Show child attributes
boolean
True when any allocation leg could not be read. The other fields are then absent, because a sum over the legs that did answer would understate the total.
string
Interest the current allocations would earn over a year at today’s supply rates, before the performance fee. In the vault’s asset.
string
The same figure after the operator’s performance fee.
number
Gross annual interest over total assets, in basis points, to two decimals. Idle funds earn nothing, so this sits below the rate of any single funded market.
null when the vault holds nothing.number
The same blended rate after the fee. This is the rate an investor earns.
integer
The fee applied to get from gross to net.
object
object
Present only on your own vault,
null on every other. current is the implementation the vault runs and platform the one the platform’s vault factory serves. The block also carries readFailed, upgradeAvailable, supportsNotice, pendingImplementation, upgradeActivatesAt, upgradeReady and pendingIsPlatform.object
Present only on your own vault,
null on every other. Carries readFailed and a markets array: the operator’s lending markets that settle in the vault’s asset and could draw on it. Each entry names the market (marketId, marketAddress, marketName, marketSymbol, borrowAssetSymbol), states both sides of the connection, and ends in a readiness verdict.readFailed: true means the RPC could not answer, not that the vault is empty. A vault whose read failed still holds every deposit it held a minute ago. Show your last verified figures with a warning, retry, and never render zeros in their place.sharePrice is an 18-decimal string regardless of the asset’s own decimals. Every other amount in the block is formatted at assetDecimals. A healthy onChain read is cached for 20 seconds, so calls inside that window see the same figures.The
interest block describes what the current allocations would earn at today’s rates. Rates move with each market’s utilization, so treat it as the present run rate rather than a forecast. It costs no extra call: the rates come from the same market read that produces the allocation legs.curl "https://api.trusset.org/lending-external-securities-v2/api/vaults/cmssh8t2u0003cghxkx1w1fwd?address=0x6a6cba16dad34f7ea7ecbcdbf050f8146b942d6b" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/lending-external-securities-v2/api/vaults/${vaultId}?address=${wallet}`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
if (!data.onChain || data.onChain.readFailed) {
scheduleRetry();
} else {
console.log(`share price ${data.onChain.sharePrice}, ${data.onChain.idleAssets} ${data.assetSymbol} idle`);
}
{
"success": true,
"data": {
"id": "cmssh8t2u0003cghxkx1w1fwd",
"own": false,
"vaultAddress": "0x4d0cfe39a3431b145d1a1393d901a36d459a1b13",
"assetAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
"assetSymbol": "USDC",
"assetDecimals": 6,
"identityRegistryAddress": "0xe9114c40934f6fb6bb317935156b731f7a86d006",
"depositorGate": {
"kind": "REGISTER",
"register": "0xe9114c40934f6fb6bb317935156b731f7a86d006",
"statement": "Deposits and share transfers are examined against this register."
},
"name": "Trusset Prime Demo Vault",
"symbol": "TPV",
"performanceFeeBps": 500,
"active": true,
"riskDisclosure": "Deposits fund overcollateralized lending markets.",
"riskDisclosureUrl": "https://bank.example/vault-risk",
"operatedBy": { "instanceName": "Trusset Client Demo", "issuerName": "Trusset UG", "isBank": true },
"onChain": {
"isOnChain": true,
"readFailed": false,
"vaultAddress": "0x4d0cfe39a3431b145d1a1393d901a36d459a1b13",
"owner": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
"asset": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
"identityRegistry": "0xe9114c40934f6fb6bb317935156b731f7a86d006",
"totalAssets": "126250.0",
"totalAssetsRaw": "126250000000",
"totalShares": "124691.358024",
"totalSharesRaw": "124691358024",
"sharePrice": "1.012500000005613861",
"idleAssets": "25000.0",
"allocatedAssets": "101250.0",
"redeemableNow": "87500.0",
"redeemableNowRaw": "87500000000",
"depositsPaused": false,
"performanceFeeBps": 500,
"blockTimestamp": 1786700400,
"assetsFullyReadable": true,
"supportsNotice": true,
"feeNotice": { "supported": true, "activatesAt": null, "delaySeconds": 604800, "ready": false },
"worstCaseHorizon": {
"horizon": "1794472800",
"bounded": true,
"complete": true,
"applies": true,
"basis": "OPEN_LOANS"
},
"allocations": [
{
"marketAddress": "0xae10e07a899526e97be3940ca6ee03af28394495",
"marketName": "Trusset Security Token",
"marketSymbol": "TRST",
"marketImageUri": null,
"lpShares": "100000000000",
"lpValue": "101250.0",
"lpValueRaw": "101250000000",
"deposited": "100000.0",
"marketAvailable": "62500.0",
"marketAvailableRaw": "62500000000",
"utilizationBps": 5503,
"borrowRateBps": 750,
"supplyRateBps": 309,
"curveBorrowRateBps": 750,
"fixedStampRateBps": null,
"drawCap": "0",
"drawCapFormatted": "0.0",
"evictionActivatesAt": null,
"exitHorizon": { "horizon": "1794472800", "bounded": true, "applies": true, "basis": "OPEN_LOANS" }
}
],
"interest": {
"readFailed": false,
"grossAnnual": "3128.625",
"netAnnual": "2972.19375",
"blendedGrossApyBps": 247.81,
"blendedNetApyBps": 235.42,
"performanceFeeBps": 500
}
},
"holder": {
"holderAddress": "0x6a6cba16dad34f7ea7ecbcdbf050f8146b942d6b",
"shares": "1000.0",
"sharesRaw": "1000000000",
"value": "1012.5",
"readFailed": false
},
"implementation": null,
"jitLiquidity": null
}
}
{
"success": true,
"data": {
"id": "cmssh8t2u0003cghxkx1w1fwd",
"name": "Trusset Prime Demo Vault",
"onChain": { "readFailed": true, "isOnChain": null },
"holder": null,
"implementation": null,
"jitLiquidity": null
}
}
{
"success": false,
"data": null,
"error": {
"code": "VAULT_NOT_FOUND",
"message": "Vault not found"
}
}
Error Codes
| Code | HTTP | Cause |
|---|---|---|
VAULT_NOT_FOUND | 404 | No such vault, or it is archived, on another network or environment, or an unpublished vault of another operator in which your instance is not a distributor of record |
VAULT_STATE_UNAVAILABLE | 503 | Whether your instance is a distributor of record in an unpublished vault could not be read from the chain. Retry shortly |
SERVICE_UNAVAILABLE | 503 | The vault records or your instance’s verified wallets could not be read. Retry shortly |
VAULT_READ_FAILED | 500 | Unexpected failure. Retry, or contact support with the request ID |
⌘I
curl "https://api.trusset.org/lending-external-securities-v2/api/vaults/cmssh8t2u0003cghxkx1w1fwd?address=0x6a6cba16dad34f7ea7ecbcdbf050f8146b942d6b" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/lending-external-securities-v2/api/vaults/${vaultId}?address=${wallet}`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
if (!data.onChain || data.onChain.readFailed) {
scheduleRetry();
} else {
console.log(`share price ${data.onChain.sharePrice}, ${data.onChain.idleAssets} ${data.assetSymbol} idle`);
}
{
"success": true,
"data": {
"id": "cmssh8t2u0003cghxkx1w1fwd",
"own": false,
"vaultAddress": "0x4d0cfe39a3431b145d1a1393d901a36d459a1b13",
"assetAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
"assetSymbol": "USDC",
"assetDecimals": 6,
"identityRegistryAddress": "0xe9114c40934f6fb6bb317935156b731f7a86d006",
"depositorGate": {
"kind": "REGISTER",
"register": "0xe9114c40934f6fb6bb317935156b731f7a86d006",
"statement": "Deposits and share transfers are examined against this register."
},
"name": "Trusset Prime Demo Vault",
"symbol": "TPV",
"performanceFeeBps": 500,
"active": true,
"riskDisclosure": "Deposits fund overcollateralized lending markets.",
"riskDisclosureUrl": "https://bank.example/vault-risk",
"operatedBy": { "instanceName": "Trusset Client Demo", "issuerName": "Trusset UG", "isBank": true },
"onChain": {
"isOnChain": true,
"readFailed": false,
"vaultAddress": "0x4d0cfe39a3431b145d1a1393d901a36d459a1b13",
"owner": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
"asset": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
"identityRegistry": "0xe9114c40934f6fb6bb317935156b731f7a86d006",
"totalAssets": "126250.0",
"totalAssetsRaw": "126250000000",
"totalShares": "124691.358024",
"totalSharesRaw": "124691358024",
"sharePrice": "1.012500000005613861",
"idleAssets": "25000.0",
"allocatedAssets": "101250.0",
"redeemableNow": "87500.0",
"redeemableNowRaw": "87500000000",
"depositsPaused": false,
"performanceFeeBps": 500,
"blockTimestamp": 1786700400,
"assetsFullyReadable": true,
"supportsNotice": true,
"feeNotice": { "supported": true, "activatesAt": null, "delaySeconds": 604800, "ready": false },
"worstCaseHorizon": {
"horizon": "1794472800",
"bounded": true,
"complete": true,
"applies": true,
"basis": "OPEN_LOANS"
},
"allocations": [
{
"marketAddress": "0xae10e07a899526e97be3940ca6ee03af28394495",
"marketName": "Trusset Security Token",
"marketSymbol": "TRST",
"marketImageUri": null,
"lpShares": "100000000000",
"lpValue": "101250.0",
"lpValueRaw": "101250000000",
"deposited": "100000.0",
"marketAvailable": "62500.0",
"marketAvailableRaw": "62500000000",
"utilizationBps": 5503,
"borrowRateBps": 750,
"supplyRateBps": 309,
"curveBorrowRateBps": 750,
"fixedStampRateBps": null,
"drawCap": "0",
"drawCapFormatted": "0.0",
"evictionActivatesAt": null,
"exitHorizon": { "horizon": "1794472800", "bounded": true, "applies": true, "basis": "OPEN_LOANS" }
}
],
"interest": {
"readFailed": false,
"grossAnnual": "3128.625",
"netAnnual": "2972.19375",
"blendedGrossApyBps": 247.81,
"blendedNetApyBps": 235.42,
"performanceFeeBps": 500
}
},
"holder": {
"holderAddress": "0x6a6cba16dad34f7ea7ecbcdbf050f8146b942d6b",
"shares": "1000.0",
"sharesRaw": "1000000000",
"value": "1012.5",
"readFailed": false
},
"implementation": null,
"jitLiquidity": null
}
}
{
"success": true,
"data": {
"id": "cmssh8t2u0003cghxkx1w1fwd",
"name": "Trusset Prime Demo Vault",
"onChain": { "readFailed": true, "isOnChain": null },
"holder": null,
"implementation": null,
"jitLiquidity": null
}
}
{
"success": false,
"data": null,
"error": {
"code": "VAULT_NOT_FOUND",
"message": "Vault not found"
}
}