Contract Status & Changelog

This documentation is the integration contract for the TBook RWA API. Implementation follows the documentation: what is written here is what ships.

Contract version	v1
Status	Implemented — the API server, SDKs, and webhook catalog track this contract; within v1, changes are additive only
Sandbox availability	Sandbox endpoints ship with the API (secret or test key required); access is arranged through your TBook contact

2026-07 — Implementation alignment release

Full claim-level alignment of this site against the shipped implementation (every endpoint, field, fee, event name, and SDK signature re-verified against source). Highlights:

• Server SDK (@tbookdev/vault-node): typed namespaces are live — accounts.*, transactions.* (build → confirm), positions.* — with idempotency-by-default (auto Idempotency-Key, same-key retries), client-side timeouts, typed error envelopes, and assertSuiTransaction decode-and-assert for pre-signing verification.
• React: @tbookdev/vault-react-sui provides the headless hooks used in every React guide.
• Webhooks: rotation now dual-signs during a 24h grace window (two v1 entries per signature header); delivery timeout and retry schedule documented to match the engine (10s, 1m/5m/30m, max 4 attempts).
• Compliance gates: business accounts require compliance.kyb.attested before the first deposit; whitelist-gated vaults run an on-chain preflight at build time (403 not_whitelisted).

Changelog

2026-08-08 — Sui gRPC migration, on-chain instant-redeem, transaction expiry

• Sui JSON-RPC is gone. Sui deactivated its network-wide JSON-RPC service at the end of July 2026. Every chain snippet in these docs now uses @mysten/sui 2.x: SuiGrpcClient for point reads and submits, @mysten/dapp-kit-react 2.x for the React provider. SuiClient, getFullnodeUrl, executeTransactionBlock, SuiClientProvider/WalletProvider no longer exist — see Quickstart, Client SDK, React hooks. This entry is late: the platform migrated on 2026-07-14 and these pages kept showing the old client for a month.
• settlement.instantRedeem is read from the contract, not declared. GET /v1/vaults/:vaultId now returns it with a source field ("chain" or "catalog-unverified") so you can tell a confirmed "off" from an unverifiable one. Never quote an instant redemption on "catalog-unverified". Previously the catalog declared available: true at 700 bps while both networks had the switch off — do not rely on any cached copy of that answer.
• Built Sui transactions now carry ValidDuring.maxEpoch (the epoch after they were built, ~24–48h). A digest the chain has never seen past that epoch is permanently absent, which is what makes releasing or refunding a held position safe.
• summary price fields are rcUSDP-only. sharePrice / estimatedShares / quotedAt come from the rcUSDP NAV source; an xaua-sui build omits them rather than pricing gold off a stablecoin's NAV.
• packageId added to GET /v1/vaults/:vaultId — the Move package the vault's calls target. Package upgrades change it: read it, don't pin it.

2026-07-08 (later) — redemption settlement pays out directly on rcusdp-sui

• transaction.redeem.settled now carries amount on rcusdp-sui: settlement transfers the proceeds straight to the account's wallet — no claim step. Verified against a live mainnet settlement cycle. Vaults that allocate a claimable balance instead keep the claimable shape (then tx/claim applies). Handle both: amount → withdrawal complete; claimable → prompt a claim.
• tx/claim remains available but is a no-op path on rcusdp-sui today (insufficient_balance when nothing was allocated).

2026-07-08 — hardened concurrency semantics, request tracing, sandbox domain

• New error code idempotency_in_progress (409): sending the same Idempotency-Key while the original request is still executing now returns a typed 409 with Retry-After: 2 instead of racing. Exactly one execution happens — the key is claimed before the handler runs. Retry with the same key to collect the replayed response. See conventions.
• @tbookdev/vault-node 0.2.1 (on npm): automatically retries 409 idempotency_in_progress with the same key, honoring Retry-After — concurrent duplicates resolve to the single original response without integration code.
• x-request-id on every response: send your own (8–64 chars, A-Z a-z 0-9 _ -) to correlate logs end-to-end, or use the one the gateway mints; errors echo it as requestId in the envelope.
• Rate limits are exact fleet-wide: fixed 60-second windows enforced per API key across all instances (per source IP when keyless). tbk_test_ keys are now limited to 1000 requests/min on sandbox (previously documented as unlimited).
• Deposit builds disclose quotedAt: the timestamp of the shared price snapshot behind sharePrice/estimatedShares — all instances quote from the same snapshot.
• Sandbox base URL is https://rwa-api-sandbox.tbook.com (previously misdocumented as sandbox.rwa-api.tbook.com).

2026-07 — documentation aligned to the current implementation

• SDKs: @tbookdev/vault-node now ships typed namespaces (accounts.*, transactions.*, positions.*), idempotency-by-default on money-movement POSTs (auto-generated Idempotency-Key, same-key retries, key echoed on results), a 30 s timeout with 2 retries on 429/5xx/network errors, and webhook verification that accepts rotation dual-signed headers. @tbookdev/vault-react-sui provides the React hooks for Sui vaults. The publishable set is @tbookdev/vault-sdk-sui, @tbookdev/vault-node, and @tbookdev/vault-react-sui — all three are published on the public npm registry.
• Webhooks: event payload examples corrected to the emitted shapes (recordId, cycleKind, claimable, reason: "cancelled" | "rollback"); treasury.withdrawal.confirmed documented as reserved; rotation dual-signing (two v1 entries, 24 h grace) documented; polling parameters corrected to types/after/limit.
• Vault economics: rcusdp-sui instant-redeem availability and fee are operator-tunable on-chain — read GET /v1/vaults/rcusdp-sui instead of hard-coding values; the 200 bps cancel fee is documented. xaua-sui subscriptions are not cancelable (400) and settle net of the subscription fee.
• Compliance: KYC (individual/omnibus) or KYB (business) attestation is required before the first deposit (403 otherwise); XAUa deposits preflight the issuer whitelist (403 not_whitelisted).

2026-06-15 — v1 draft published

• Initial publication of the v1 contract: account models (individual / omnibus / treasury / business), asset & vault catalog with rails, build–sign–submit–confirm transaction model, positions/earnings/portfolio, analytics, treasury controls, webhook catalog, sandbox endpoints.
• Supersedes all previously published "Yield Layer" API descriptions on this site (single-vault routes, pk_test_/sk_test_ key prefixes, epoch-named webhook events). Integrations should target this contract only.

How changes land

• Changes to the contract are published here before they ship.
• Within v1, changes are additive only — see Versioning and forward compatibility.
• Questions or feedback: through your TBook contact.