Pilot environment: testnet, simulated yield, mocked fiat rails — read the disclosure
API referenceChangelog
Positions

Your position in a vault, decomposed by sub-account, with what it has earned

The ledger fold: what each sub-account holds, what is reserved against withdrawals in flight, and what is available. The totals are the SUM of the sub-accounts, alongside the share balance of the omnibus wallet TCB holds for you. Share amounts are decimal strings at the vault's own share scale. Each row carries what it has earned — lifetime, unrealised, realised and, when you name a period, over that period — valued at the vault's latest observed share price, which is returned with its block and time. rate is the annual rate the vault pays now, net of fees, read on-chain, with when it took effect and the next scheduled change. A figure that cannot be observed is null with the reason in notObserved; it is never zero.

GET
/api/partner/v1/positions

The ledger fold: what each sub-account holds, what is reserved against withdrawals in flight, and what is available. The totals are the SUM of the sub-accounts, alongside the share balance of the omnibus wallet TCB holds for you. Share amounts are decimal strings at the vault's own share scale. Each row carries what it has earned — lifetime, unrealised, realised and, when you name a period, over that period — valued at the vault's latest observed share price, which is returned with its block and time. rate is the annual rate the vault pays now, net of fees, read on-chain, with when it took effect and the next scheduled change. A figure that cannot be observed is null with the reason in notObserved; it is never zero.

Authorization

bearer
AuthorizationBearer <token>

In: header

Query Parameters

currency*string

The vault's currency (ISO 4217). Required: a share balance with no vault named is a number nobody can act on.

periodFrom?string

First day (UTC, YYYY-MM-DD, inclusive) of earnedPeriod. Send with periodTo.

periodTo?string

Last day (UTC, YYYY-MM-DD, inclusive) of earnedPeriod, at most 366 days after periodFrom. A period is closed by the next day's share-price observation, so one ending today is null until tomorrow.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/partner/v1/positions?currency=USD&periodFrom=2026-10-01&periodTo=2026-10-07"
{  "data": {    "currency": "USD",    "disclosure": {      "items": [        "ENVIRONMENT_IS_TESTNET: The environment is a testnet (Arbitrum Sepolia). No mainnet deployment exists.",        "YIELD_IS_SIMULATED: The vault rate is set administratively and the interest it produces is minted as fresh underlying, not earned. It does not represent a return generated by deployed capital.",        "FIAT_RAILS_ARE_MOCKED: No real fiat movement occurs. Balances are ledger entries against a sandbox provider.",        "CONVERSION_RATES_ARE_MARKET_QUOTED_OR_REFUSED: A conversion is priced only by an external venue that quotes independently of TCB. When no such venue can price the pair, the conversion is refused rather than priced from an internal table. Read rate.pricingModel on every conversion: MARKET is a venue quote; any other value is not a market rate and must not be presented as one.",        "CONTRACTS_ARE_UNAUDITED: No audit has been performed. Mainnet is gated on a two-firm audit that has not been commissioned.",        "CUSTODY_IS_TCB_SUBACCOUNT: Everything held for the client — its vault shares, and the tcbUSD it holds between the steps of the tokenised deposit chain — is held in TCB custody, in the one TCB wallet assigned to the client. The client holds no keys and moves those tokens only through this API; each sub-account's shares and tcbUSD are book entries against what that wallet holds.",        "INTEGRATION_AGREEMENT_ONLY: Fees as published on the rate card; no yield share, no return commitment."      ],      "summary": "This is a pilot integration on a testnet. Nothing in this system earns anything: the yield is simulated and the fiat rails are mocked.",      "version": "2026-10-27"    },    "rate": {      "apyBps": 400,      "asOf": "2026-10-09T12:00:00.000Z",      "effectiveFrom": "2026-09-01T00:00:00.000Z",      "nextChange": {        "apyBps": 375,        "effectiveFrom": "2026-11-01T00:00:00.000Z"      },      "pendingChange": {        "apyBps": 375,        "effectiveFrom": "2026-11-01T00:00:00.000Z"      },      "stale": false,      "unavailableReason": null    },    "sharePrice": {      "asOfAt": "2026-10-06T00:00:05.000Z",      "asOfBlock": "316183526",      "snapshotDate": "2026-10-06",      "stale": false,      "value": "1.002480000000000000"    },    "subAccounts": [      {        "accrual": {          "currentValue": "1002.480000",          "deposited": "1000.000000",          "earnedLifetime": "2.480000",          "earnedPeriod": {            "deposited": "0",            "earned": "0.810000",            "from": "2026-10-01",            "notObserved": [],            "to": "2026-10-07",            "withdrawn": "0"          },          "earnedRealised": "0",          "earnedUnrealised": "2.480000",          "netContributions": "1000.000000",          "notObserved": [],          "withdrawn": "0"        },        "availableShares": "1024.518330000000000000000000",        "externalRef": "acme-fund-002",        "isDefault": false,        "label": "Growth Fund II",        "reservedShares": "0",        "settledShares": "1024.518330000000000000000000",        "subAccountId": "5d3b8e10-2f47-4c9a-b6e8-0a71d4c2f395"      }    ],    "totals": {      "accrual": {        "currentValue": "1002.480000",        "deposited": "1000.000000",        "earnedLifetime": "2.480000",        "earnedPeriod": {          "deposited": "0",          "earned": "0.810000",          "from": "2026-10-01",          "notObserved": [],          "to": "2026-10-07",          "withdrawn": "0"        },        "earnedRealised": "0",        "earnedUnrealised": "2.480000",        "netContributions": "1000.000000",        "notObserved": [],        "withdrawn": "0"      },      "availableShares": "1024.518330000000000000000000",      "reservedShares": "0",      "settledShares": "1024.518330000000000000000000",      "walletShares": "1024.518330000000000000000000"    },    "vault": {      "address": "0x7a2fD3c8e91B4A5d06E7c1F2b38A9d4C5e6f0B12",      "chain": "ARBITRUM"    }  },  "success": true,  "timestamp": "2026-09-02T10:15:30.000Z"}

Fetch one conversion by id GET

The conversion in its CURRENT state, whatever that is — including a terminal failure, reported here as the object rather than as an error. This is the fetch half of the thin webhook payloads (a *.settled / *.failed event carries only a resource pointer) and the poll surface the money errors point at.

A vault's observed share price, day by day GET

One entry per UTC day in the range, oldest first: the share price as first observed that day, with the chain block it was read at and when. A day the price was not observed is returned with nulls, never a zero and never filled from a neighbouring day.