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 (headless hooks over dapp-kit + react-query) replaces the legacy Solana hooks package in all guides.
• 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).
• Solana rail frozen: rcusdp-sol is paused — new deposits/redeems return 409 vault_paused; claim/cancel remain open for exits. All Solana-specific integration guidance has been removed; the platform is chain-decoupled with Sui as the active rail.

Changelog

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

• Sui-first: the Solana gateway rail (rcusdp-sol) is frozen — the vault is paused, deposit/redeem builds return 409 vault_paused, and claim/cancel-deposit stay open so balances can exit. Solana-specific integration guidance has been removed; the architecture remains chain-decoupled and accounts may still declare sui or solana wallets.
• 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.