Skip to main content

Sandbox Endpoints

Two endpoints that exist only on rwa-api-sandbox.tbook.com — calling them in production returns not_found. They require a secret or test key (tbk_secret_* / tbk_test_*; publishable keys get 403 permission_denied).

POST /v1/sandbox/settle​

Request a settlement cycle on demand instead of waiting for the daily run. This is a trigger, not the executor — the actual settlement is run by the operator tooling.

Body: {vaultId} — must reference a catalog vault.

Response 202:

{
  "accepted": true,
  "requestId": "evt_…",
  "vaultId": "rcusdp-sui",
  "note": "Settlement cycle triggered; track via GET /v1/events (sandbox.settle.requested) — settled webhooks follow once the operator cycle runs"
}
curl -X POST $BASE/v1/sandbox/settle \
  -H "Authorization: Bearer $TBK_TEST_KEY" -H "Content-Type: application/json" \
  -d '{"vaultId": "rcusdp-sui"}'

The request is recorded as a sandbox.settle.requested event — poll GET /v1/events to see when it was requested and whether it was forwarded to the settlement automation. Once the operator cycle runs, the usual vault.cycle.settled and per-account transaction.*.settled webhooks follow.

Errors: invalid_request (unknown vaultId) · internal_error (settlement automation unreachable).

POST /v1/sandbox/faucet​

Request test funds for an account's wallets. Where a programmatic faucet exists (Sui testnet gas), the request is made for you; everything else returns instructions and public faucet links.

Body: {accountId}

{
  "accountId": "acct_…",
  "results": {
    "sui": {
      "gas": "requested",
      "usdc": "use https://faucet.circle.com (Sui testnet) for test USDC"
    }
  }
}

results is keyed by chain, one entry per wallet on the account. Errors: not_found (unknown account).

See Test Funds for the full faucet guide.