The sandbox: reference
Try Thank with HeartBank® end to end before anything counts: test persons, and test passkeys your code or an agent can press. Nothing in it is real. Thank's own calls run here at https://sandbox.333.eco/ledger (/v1/prepare, /v1/commit, /v1/place, /v1/aura; your assertion's aud is that base address, as https://ledger.333.eco in production), and the press page at https://sandbox.333.eco/press.
The developers' sandbox (developers.333.eco SPEC §8.1), read from its live code: repo 333eco/developers.333.eco, sandbox/src/server.ts. The sandbox ledger at https://sandbox.333.eco/ledger is the ledger's own code: its API is Thank with HeartBank®'s, at that address. These are the sandbox's own steps: test persons in place of a person's log-in, and the twins of login.333.eco's /press/hint and /press/wrap (same request, same answer); /press/api is the one step that exists only here.
⛔ Nothing in it is real. A test person is nobody; a press made here is a test passkey's, for sandbox.333.eco, and verifies nowhere else; every Monday 00:00–00:15 UTC nothing is written while the week rolls: last week's log gets its last checkpoint, then the thanks and the places are wiped and a new log begins (test persons stay). An app is in the sandbox once it has asked for Log in on the dashboard (approval isn't needed here). At most 20 test persons and 1,000 prepares per app per UTC day.
The week's log: each week has its own log, named sandbox.333.eco/log/<its Monday, YYYY-MM-DD>, and a receipt names the week it was written in. Its files are at https://sandbox.333.eco/log/<Monday>/: checkpoint (a signed note, the one file that changes), checkpoints/<size>, tile/… (C2SP tlog-tiles), vkey (the week's verifier key, Ed25519, named for that week, so a checkpoint verifies under one week only) and, once the week has ended, final (its last size). The log closes once a day at 00:05 UTC, so a thank appears in the next day's checkpoint; the week's files stay 7 days after it ends. Like production, your app gets only a receipt's id: the whole receipt goes to its person's own record, which the sandbox does not have, so here you check the tree (the checkpoint against the vkey, the root from the tiles), not your own receipt.
Your assertion, everywhere here: a fresh ES256 JWT, iss = sub = your app's Log-in client id (hbc_…; get_app and the dashboard show it), one-use jti, at most 5 minutes old. aud is the exact address called for the sandbox's own steps (/persons, /persons/{id}, /press/hint, /press/api), and the ledger's base address, https://sandbox.333.eco/ledger, for every ledger call. A kid in the header is optional: with one key at your key URL it is found without it; send it when you publish several. /press/wrap takes no assertion: it knows the app from the result itself.
GET https://sandbox.333.eco/persons
Your app's test persons
Every test person of the calling app, oldest first, each with a fresh pidToken (as each log-in gives one).
Who may call it: Your app's server proves itself as it does at the ledger: a fresh ES256 JWT, iss = sub = your app's Log-in client id (hbc_…), aud = the exact address called, at most 5 minutes old, a jti never used before. Your keys are read from the key URL on your app's Log in. ⛔ Never sent from a browser or a phone.
Answers
200 The test persons. { persons }401 Not an app the sandbox knows, or a bad assertion. { error }
What a success answer holds
| Field | Type | What it is |
|---|
persons | object[] | |
On the MCP server: not a tool: your app's server, with its own key; an agent uses the developer tool sandbox_add_person, behind sign-on
POST https://sandbox.333.eco/persons
Make a test person
At most 20 per app. They stay through the weekly wipe, until removed or the app is deleted.
Who may call it: Your app's server proves itself as it does at the ledger: a fresh ES256 JWT, iss = sub = your app's Log-in client id (hbc_…), aud = the exact address called, at most 5 minutes old, a jti never used before. Your keys are read from the key URL on your app's Log in. ⛔ Never sent from a browser or a phone.
Body application/json
| Field | Type | What it is |
|---|
label | string | Your own name for them, such as Alice. |
Answers
200 The new test person. { person }400 A bad label. { error }401 Not an app the sandbox knows, or a bad assertion. { error }409 Already 20. { error }
What a success answer holds
| Field | Type | What it is |
|---|
person | { id, label, sub, pidToken } | |
person.id | string | The test person's id here; the one /press/api and the page press as. |
person.label | string | Your own name for them (1 to 40 characters). |
person.sub | string | Your app's id for them, as Log in gives one. |
person.pidToken | string | As Log in's pid_token claim: signed by the sandbox and sealed to the sandbox ledger. A fresh one each time; good for 180 days; the sandbox's alone. |
On the MCP server: not a tool: a write; an agent uses the developer tool sandbox_add_person, behind sign-on
DELETE https://sandbox.333.eco/persons/{id}
Remove a test person
Who may call it: Your app's server proves itself as it does at the ledger: a fresh ES256 JWT, iss = sub = your app's Log-in client id (hbc_…), aud = the exact address called, at most 5 minutes old, a jti never used before. Your keys are read from the key URL on your app's Log in. ⛔ Never sent from a browser or a phone.
Parameters
| Name | Type | What it is |
|---|
id (path) | string | |
Answers
200 Removed. { deleted }401 Not an app the sandbox knows, or a bad assertion. { error }404 No test person of your app has that id. { error }
What a success answer holds
| Field | Type | What it is |
|---|
deleted | true | |
On the MCP server: not a tool: a write, on your app's own key
POST https://sandbox.333.eco/press/hint
Which test person is the giver (twin of login.333.eco/press/hint)
The same request and answer as production's: the hint narrows the press page to the giver. A narrowing, never a gate.
Who may call it: Sent as FORM fields, not a header, as at login.333.eco: client_assertion_type = urn:ietf:params:oauth:client-assertion-type:jwt-bearer and client_assertion = the same ES256 JWT, aud = this endpoint's address.
Body application/x-www-form-urlencoded
| Field | Type | What it is |
|---|
client_assertion_type | "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" | |
client_assertion | string | |
sub | string | Your app's id for the giver. |
Answers
200 A hint for the press page's hint fragment field. { hint }401 A bad assertion. { error }403 Not an app the sandbox knows. { error }404 No test person of your app has that sub. { error }
What a success answer holds
| Field | Type | What it is |
|---|
hint | string | |
On the MCP server: not a tool: your app's server, with its own key
POST https://sandbox.333.eco/press/api
A test press, for code and agents (the sandbox only)
Presses a test person's test passkey for a ticket the sandbox ledger's prepare returned, and returns the same result the press page brings back to your return page. ⛔ Only here: in production every press is a person's own passkey. ⛔ Only a ticket the sandbox ledger signed, and only your own app's.
Who may call it: Your app's server proves itself as it does at the ledger: a fresh ES256 JWT, iss = sub = your app's Log-in client id (hbc_…), aud = the exact address called, at most 5 minutes old, a jti never used before. Your keys are read from the key URL on your app's Log in. ⛔ Never sent from a browser or a phone.
Body application/json
| Field | Type | What it is |
|---|
ticket | string | |
person | string | The test person who presses: for a Kiitos, the giver. |
Answers
200 The result, good once and for 2 minutes, at /press/wrap. { result }400 Not a ticket the sandbox ledger made, or it expired (unknown_flow). { error }401 Not an app the sandbox knows, or a bad assertion. { error }403 Another app's ticket. { error }404 No test person of your app has that id. { error }
What a success answer holds
| Field | Type | What it is |
|---|
result | string | |
On the MCP server: not a tool: your app's own key; an agent uses the developer tool sandbox_press, behind sign-on
POST https://sandbox.333.eco/press/wrap
Exchange a result for a pressToken (twin of login.333.eco/press/wrap)
The same request and answer as production's: the press result from the press page (or /press/api), exchanged by your server for the pressToken POST /ledger/v1/commit takes.
Who may call it: anyone, no key
Body application/x-www-form-urlencoded
| Field | Type | What it is |
|---|
result | string | |
Answers
200 The pressToken for POST /ledger/v1/commit. { pressToken }400 The result was refused, or already used (replayed). { error }403 The result names an app the sandbox doesn't know (it reads the app from the result, which only the sandbox could have signed). { error }
What a success answer holds
| Field | Type | What it is |
|---|
pressToken | string | |
On the MCP server: not a tool: your app's server, after the test press