Distributor Fees
Get Earnings
What your instance earns as a distributor in one vault, and the operator’s view for its own vault
GET
/
lending-external-securities-v2
/
api
/
vaults
/
{vaultId}
/
earnings
curl "https://api.trusset.org/lending-external-securities-v2/api/vaults/cmssh8t2u0003cghxkx1w1fwd/earnings" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/lending-external-securities-v2/api/vaults/${vaultId}/earnings`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
if (data.supported) {
console.log(`earned ${data.earned.value}, claimable ${data.claimable.value} ${data.asset.symbol}`);
if (data.approval.note) console.warn(data.approval.note);
}
{
"success": true,
"data": {
"vaultId": "cmssh8t2u0003cghxkx1w1fwd",
"vaultAddress": "0x4d0cfe39a3431b145d1a1393d901a36d459a1b13",
"asset": { "address": "0x98ad0ca091552e23c564b41c74282e5343d03e8a", "symbol": "USDC", "decimals": 6 },
"distributor": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"distributors": ["0x83fd50068b2fc776bbf237f8163495b2247408c1"],
"supported": true,
"earned": { "raw": "16250000", "value": "16.25" },
"paid": { "raw": "12500000", "value": "12.5" },
"claimable": { "raw": "3750000", "value": "3.75" },
"uncollectedEstimate": { "raw": "4000000", "value": "4.0" },
"attributedShares": { "raw": "24938271605", "value": "24938.271605" },
"shareOfVaultBps": 2000,
"boundHolders": 3,
"wallets": [
{
"distributor": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"payoutWallet": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"claimable": { "raw": "3750000", "value": "3.75" },
"attributedShares": { "raw": "24938271605", "value": "24938.271605" },
"approved": true
}
],
"approval": {
"required": true,
"owner": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
"approved": true,
"note": null
},
"markets": [
{
"marketAddress": "0xae10e07a899526e97be3940ca6ee03af28394495",
"marketName": "TRST / USDC",
"vaultClaim": { "raw": "20000000", "value": "20.0" },
"yourShareEstimate": { "raw": "4000000", "value": "4.0" },
"routed": true,
"funds": true,
"readFailed": false
}
],
"payouts": [
{
"distributor": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"wallet": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"amount": { "raw": "12500000", "value": "12.5" },
"txHash": "0xa3b3376bfa1263cddfea82d92ef29d70014bc3539d065a9e8b1f3a3150f5e8fd",
"at": "2026-09-20T10:15:00.000Z"
}
],
"vault": {
"totalShares": { "raw": "124691358024", "value": "124691.358024" },
"attributedShares": { "raw": "62345679012", "value": "62345.679012" },
"feeCashHeld": { "raw": "9375000", "value": "9.375" },
"collected": { "raw": "46875000", "value": "46.875" },
"collectedAttributed": { "raw": "23437500", "value": "23.4375" }
},
"history": { "complete": true, "asOfBlock": 9284113, "basis": "FINALIZED", "note": null }
}
}
{
"operator": {
"owner": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
"claimable": { "raw": "5625000", "value": "5.625" },
"paid": { "raw": "18750000", "value": "18.75" },
"otherDistributors": [
{
"distributor": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"payoutWallet": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"claimable": { "raw": "3750000", "value": "3.75" },
"attributedShares": { "raw": "24938271605", "value": "24938.271605" }
}
],
"otherDistributorsReadFailed": false,
"approvalsSupported": true,
"approvedDistributors": [
{ "distributor": "0x83fd50068b2fc776bbf237f8163495b2247408c1", "approved": true }
],
"approvedDistributorsReadFailed": false
}
}
Returns what the instance behind the API key earns as a distributor in one vault. That is what it has been paid, what the vault holds for it now, and an estimate of its part still waiting on the markets. Every figure covers your instance’s own verified wallets only. The vault’s operator also gets an
operator block with its own share and every other distributor’s standing.
Any vault visible to your instance can be read, including an unpublished one in which your instance is a distributor of record.
How a distributor earns
The instance whose API key builds a depositor’s first attributed deposit becomes that depositor’s distributor. That holds for Deposit and for a market’s Deposit to Vault route alike. The vault binds the holder to that instance’s distributor wallet once and attributes every share the holder has or later receives to it. As borrowers repay, each market the vault funds sets aside a distributor share for its liquidity providers. That share is 5 percent of the interest left after Trusset’s 15 percent infrastructure fee, plus 5 percent of each fixed transaction fee. The vault’s part is its slice, and it waits on the market until someone collects it.- Collect Distributor Fees pulls one market’s slice into the vault. The vault credits the part earned by attributed shares to their distributors and the rest, earned by shares no distributor brought, to the vault operator.
- Pay Distributor sends a distributor’s credit to its payout wallet. Pay Operator Fees sends the operator’s credit to the vault owner.
When the figures are read
The payout history comes from the vault’s events, recorded up to the last settled block. That is the finalized block, or five blocks behind the head on a chain that reports no finality. Whenhistory.complete is true, the balances, claims and payout history are all read at history.asOfBlock. The page then trails the chain head by the finality delay, and a payout you just confirmed appears once its block is final.
When history.complete is false, the vault and market figures are read live and paid and earned cover only the blocks read so far. A vault created in a block that is not final yet carries history.pendingFinality: true until it is.
Path Parameters
string
required
Vault ID.
Response Fields
Every amount is an object{ raw, value }: raw in base units of the vault’s asset, value formatted at its decimals.
object
Show child attributes
Show child attributes
string
The vault read.
string
The vault contract.
object
address, symbol and decimals of the vault’s asset.string
Your instance’s distributor wallet, the one a deposit through your API key names.
null when your instance has no verified wallet.array
Every verified wallet of your instance. The totals below sum over all of them, so a holder bound to an earlier primary wallet that is still verified counts.
boolean
false when the vault runs an implementation from before distributor attribution. The response then carries only the fields above and a reason: no deposit is attributed and nothing is earned until its operator upgrades it.object
paid plus claimable: everything your instance has earned in this vault that has reached the vault.object
Distributor fees the vault has paid to your instance’s payout wallets.
object
Distributor fees the vault holds for your instance now, payable at once through Pay Distributor.
object
An estimate of your part of the slices still waiting on the markets. It scales each market’s claim by your share of the vault’s shares today. The vault credits by the attribution in force while the interest accrued, so the amount credited on collection can differ.
object
Vault shares attributed to your instance.
integer
Those shares as a share of all shares in issue, in basis points.
0 when no shares are in issue.integer
Holders bound to your instance’s wallets in this vault.
array
One entry per wallet in
distributors, with distributor, payoutWallet, claimable, attributedShares and approved. payoutWallet is where Pay Distributor sends its fees. approved says whether a deposit may bind a new holder to that wallet.object
Whether deposits through your API key bind new holders to your instance.
Show child attributes
Show child attributes
boolean
true when the vault binds a holder only to its owner or an approved distributor. false on an implementation that binds to any distributor a deposit names.string
The vault owner, who grants approvals.
boolean
Whether your instance’s distributor wallet is approved, or is the owner.
string
Set when approval is required and missing. Until the operator approves your wallet, deposits your instance brings name no distributor and their share goes to the vault operator.
array
Every market the vault funds or has consented to draw for, plus any market it left that still holds a slice for it.
Show child attributes
Show child attributes
string
The lending market.
string
A label such as
TRST / USDC, or null when the market is not on record.object
The vault’s slice waiting on that market.
null when unreadable.object
Your estimated part of it.
null when the claim is unreadable, routed is false, or no shares are in issue.boolean
true when the market holds the slice for the vault to collect itself. false when the market would pay it elsewhere, so a collection fails with DISTRIBUTOR_SLICE_NOT_ROUTED. null when there is no claim or the check was inconclusive.boolean
Whether the vault currently funds the market or has consented to draw for it.
boolean
true when the claim could not be read.array
Your instance’s last 50 payouts, newest first:
distributor, wallet, amount, txHash and at.object
Vault-wide totals.
totalShares and attributedShares count shares in issue and shares attributed to any distributor. feeCashHeld is collected distributor fees the vault still holds for distributors and the operator. collected sums every collection so far, and collectedAttributed the part credited to distributors.object
complete, asOfBlock, basis (FINALIZED or CONFIRMATIONS), note when incomplete, and pendingFinality with createdInBlock while the vault’s creation block is not final.object
Present only when your instance operates the vault.
Show child attributes
Show child attributes
string
The vault owner, which receives the operator’s credit.
object
The unattributed slice the vault holds for the operator now, payable through Pay Operator Fees.
null when unreadable.object
What the vault has paid its owner so far.
array
Every other distributor with holders bound to it and shares or unpaid fees in the vault:
distributor, payoutWallet, claimable, attributedShares. null when unreadable.boolean
true when otherDistributors could not be read.boolean
Whether the vault’s implementation has distributor approvals.
array
{ distributor, approved } for every distributor ever named in an approval on this vault, read live, approved first. null when unreadable.boolean
true when approvedDistributors could not be read.curl "https://api.trusset.org/lending-external-securities-v2/api/vaults/cmssh8t2u0003cghxkx1w1fwd/earnings" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/lending-external-securities-v2/api/vaults/${vaultId}/earnings`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
if (data.supported) {
console.log(`earned ${data.earned.value}, claimable ${data.claimable.value} ${data.asset.symbol}`);
if (data.approval.note) console.warn(data.approval.note);
}
{
"success": true,
"data": {
"vaultId": "cmssh8t2u0003cghxkx1w1fwd",
"vaultAddress": "0x4d0cfe39a3431b145d1a1393d901a36d459a1b13",
"asset": { "address": "0x98ad0ca091552e23c564b41c74282e5343d03e8a", "symbol": "USDC", "decimals": 6 },
"distributor": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"distributors": ["0x83fd50068b2fc776bbf237f8163495b2247408c1"],
"supported": true,
"earned": { "raw": "16250000", "value": "16.25" },
"paid": { "raw": "12500000", "value": "12.5" },
"claimable": { "raw": "3750000", "value": "3.75" },
"uncollectedEstimate": { "raw": "4000000", "value": "4.0" },
"attributedShares": { "raw": "24938271605", "value": "24938.271605" },
"shareOfVaultBps": 2000,
"boundHolders": 3,
"wallets": [
{
"distributor": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"payoutWallet": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"claimable": { "raw": "3750000", "value": "3.75" },
"attributedShares": { "raw": "24938271605", "value": "24938.271605" },
"approved": true
}
],
"approval": {
"required": true,
"owner": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
"approved": true,
"note": null
},
"markets": [
{
"marketAddress": "0xae10e07a899526e97be3940ca6ee03af28394495",
"marketName": "TRST / USDC",
"vaultClaim": { "raw": "20000000", "value": "20.0" },
"yourShareEstimate": { "raw": "4000000", "value": "4.0" },
"routed": true,
"funds": true,
"readFailed": false
}
],
"payouts": [
{
"distributor": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"wallet": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"amount": { "raw": "12500000", "value": "12.5" },
"txHash": "0xa3b3376bfa1263cddfea82d92ef29d70014bc3539d065a9e8b1f3a3150f5e8fd",
"at": "2026-09-20T10:15:00.000Z"
}
],
"vault": {
"totalShares": { "raw": "124691358024", "value": "124691.358024" },
"attributedShares": { "raw": "62345679012", "value": "62345.679012" },
"feeCashHeld": { "raw": "9375000", "value": "9.375" },
"collected": { "raw": "46875000", "value": "46.875" },
"collectedAttributed": { "raw": "23437500", "value": "23.4375" }
},
"history": { "complete": true, "asOfBlock": 9284113, "basis": "FINALIZED", "note": null }
}
}
{
"operator": {
"owner": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
"claimable": { "raw": "5625000", "value": "5.625" },
"paid": { "raw": "18750000", "value": "18.75" },
"otherDistributors": [
{
"distributor": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"payoutWallet": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"claimable": { "raw": "3750000", "value": "3.75" },
"attributedShares": { "raw": "24938271605", "value": "24938.271605" }
}
],
"otherDistributorsReadFailed": false,
"approvalsSupported": true,
"approvedDistributors": [
{ "distributor": "0x83fd50068b2fc776bbf237f8163495b2247408c1", "approved": true }
],
"approvedDistributorsReadFailed": false
}
}
Error Codes
| Code | HTTP | Cause |
|---|---|---|
VAULT_NOT_FOUND | 404 | No such vault, or it is not visible to your instance |
VAULT_NOT_DEPLOYED | 409 | The vault has no on-chain address on record |
VAULT_STATE_UNAVAILABLE | 503 | The vault’s implementation, its attribution, a distributor’s standing, or your standing in an unpublished vault could not be read. Retry shortly |
CHAIN_UNAVAILABLE | 503 | The chain could not be read, so nothing was decided. Retry shortly |
SERVICE_UNAVAILABLE | 503 | The vault records or your instance’s verified wallets could not be read. Retry shortly |
VAULT_EARNINGS_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/earnings" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/lending-external-securities-v2/api/vaults/${vaultId}/earnings`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
if (data.supported) {
console.log(`earned ${data.earned.value}, claimable ${data.claimable.value} ${data.asset.symbol}`);
if (data.approval.note) console.warn(data.approval.note);
}
{
"success": true,
"data": {
"vaultId": "cmssh8t2u0003cghxkx1w1fwd",
"vaultAddress": "0x4d0cfe39a3431b145d1a1393d901a36d459a1b13",
"asset": { "address": "0x98ad0ca091552e23c564b41c74282e5343d03e8a", "symbol": "USDC", "decimals": 6 },
"distributor": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"distributors": ["0x83fd50068b2fc776bbf237f8163495b2247408c1"],
"supported": true,
"earned": { "raw": "16250000", "value": "16.25" },
"paid": { "raw": "12500000", "value": "12.5" },
"claimable": { "raw": "3750000", "value": "3.75" },
"uncollectedEstimate": { "raw": "4000000", "value": "4.0" },
"attributedShares": { "raw": "24938271605", "value": "24938.271605" },
"shareOfVaultBps": 2000,
"boundHolders": 3,
"wallets": [
{
"distributor": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"payoutWallet": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"claimable": { "raw": "3750000", "value": "3.75" },
"attributedShares": { "raw": "24938271605", "value": "24938.271605" },
"approved": true
}
],
"approval": {
"required": true,
"owner": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
"approved": true,
"note": null
},
"markets": [
{
"marketAddress": "0xae10e07a899526e97be3940ca6ee03af28394495",
"marketName": "TRST / USDC",
"vaultClaim": { "raw": "20000000", "value": "20.0" },
"yourShareEstimate": { "raw": "4000000", "value": "4.0" },
"routed": true,
"funds": true,
"readFailed": false
}
],
"payouts": [
{
"distributor": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"wallet": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"amount": { "raw": "12500000", "value": "12.5" },
"txHash": "0xa3b3376bfa1263cddfea82d92ef29d70014bc3539d065a9e8b1f3a3150f5e8fd",
"at": "2026-09-20T10:15:00.000Z"
}
],
"vault": {
"totalShares": { "raw": "124691358024", "value": "124691.358024" },
"attributedShares": { "raw": "62345679012", "value": "62345.679012" },
"feeCashHeld": { "raw": "9375000", "value": "9.375" },
"collected": { "raw": "46875000", "value": "46.875" },
"collectedAttributed": { "raw": "23437500", "value": "23.4375" }
},
"history": { "complete": true, "asOfBlock": 9284113, "basis": "FINALIZED", "note": null }
}
}
{
"operator": {
"owner": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
"claimable": { "raw": "5625000", "value": "5.625" },
"paid": { "raw": "18750000", "value": "18.75" },
"otherDistributors": [
{
"distributor": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"payoutWallet": "0x83fd50068b2fc776bbf237f8163495b2247408c1",
"claimable": { "raw": "3750000", "value": "3.75" },
"attributedShares": { "raw": "24938271605", "value": "24938.271605" }
}
],
"otherDistributorsReadFailed": false,
"approvalsSupported": true,
"approvedDistributors": [
{ "distributor": "0x83fd50068b2fc776bbf237f8163495b2247408c1", "approved": true }
],
"approvedDistributorsReadFailed": false
}
}