Dev Faucet

Type: NONE · Weight: 1

Status: Implemented (development environments only).

POST /api/v3/dev/faucet

Seed a Canton party's spot balances with a fixed starter kit so a demo works without a manual database seed. The route is always mounted, but it only functions when the gateway is started with the environment variable SPOT_DEV_FAUCET=1; in every other deployment (including production) it returns 403. No authentication of any kind is required when it is enabled.

Request — JSON body

POST /api/v3/dev/faucet
Content-Type: application/json

{ "party": "<canton-party-id>" }

Field	Type	Required	Notes
party	string	yes	Canton party id; trimmed, must be non-empty. The spot account is the same deterministic UUIDv5 that session-key derives.

Behaviour

The balances are set, not added: for each seeded asset, free is overwritten with the starter amount and locked is reset to 0, regardless of the previous value.

Asset	free after the call
CUSD	10000
CBTC	1
cETH	10
USX	10000
aCC	1
USDC.B	10000
USDCx	10000

CC is not seeded.

Response — 200

{
  "userId": "7c2d1f0e-3a4b-5c6d-8e9f-0a1b2c3d4e5f",
  "seeded": [
    ["CUSD", "10000"], ["CBTC", "1"], ["cETH", "10"], ["USX", "10000"],
    ["aCC", "1"], ["USDC.B", "10000"], ["USDCx", "10000"]
  ]
}

Field	Type	Notes
userId	string	The party's spot account id.
seeded	array of [asset, amount] string pairs	The amounts written, in the order above.

Errors — HTTP status only, no {code,msg} body (except 429)

HTTP	cause
400	party empty, or body not valid JSON.
403	Faucet disabled (SPOT_DEV_FAUCET is not 1). This is the production response.
429	-1003 — per-IP public weight exhausted.
500	Database failure.