HTTP API
Two services: the app's own routes at app.darwin.market/api/*, and the relay at darwin-relay.fly.dev. The browser never calls the relay directly; the app's /api/relay-* routes forward to it server-side.
Prices (public)
| Route | Returns |
|---|---|
GET /api/price/BLUEDW | NAV per share in USD, faucet id (hex and bech32), decimals, vault value, supply, real composition, asOf. CORS open. This is the priceUrl a wallet uses to price BLUEDW |
GET /api/nav-v?faucet=<vault> | The vault value V and per-coin holdings, from the vault and Pragma. The relay reads it for the basket size cap |
GET /api/prices | Coin prices from Pragma, falling back to CoinGecko only if the oracle is stale |
GET /api/pragma-prices | Pragma's medians, read from the publisher's storage over gRPC |
Example:
GET /api/price/BLUEDW
{
"symbol": "BLUEDW", "name": "Darwin Blue Chip",
"faucetId": "mm1art7wz4563p0u5fkjwx053tztqz3w23c",
"faucetIdHex": "0xd7e70ab4d442fe5136938cfa456258",
"decimals": 8, "usd": 0.967153, "method": "nav",
"vaultValueUsd": 236.27, "supply": 244.29,
"composition": [
{ "faucetId": "mm1aqcgf57r38kwe52lm2thp5vv3g4af6h4", "weight": 0.5103 },
{ "faucetId": "mm1apqelr6tlaeftyfj4f7w59dycysmtawe", "weight": 0.2941 },
{ "faucetId": "mm1ar608hfk0zvhsy2jy9jryzlyhcdy7fv7", "weight": 0.1956 }
],
"asOf": "2026-11-10T11:21:39.670Z"
}Trades (through the relay)
| App route | Relay route | Does |
|---|---|---|
POST /api/relay-deposit | POST /relay/deposit | Hands the relay your buy note file |
POST /api/relay-redeem | POST /relay/redeem | Hands the relay your sell note file |
GET /api/relay-status?note= | GET /relay/status | A trade's state and step. Details only with a view proof |
GET/POST /api/relay-shares | /relay/shares | Fetch and acknowledge your share note (proof required) |
GET/POST /api/relay-returns | /relay/returns | Fetch and acknowledge your sell's USDCx note (proof required) |
POST /api/relay-lookup | POST /relay/lookup | Your trades, by {note, proof} pairs. Only notes whose proof verifies come back |
GET /api/relay-health | GET /health | Relay status, whether buys are paused, beta caps and current basket size |
A trade's proof is sent as the x-darwin-proof header: sha256("darwin.relay.view.v1|" + noteId + "|" + serial felts). See Confidentiality Model. Listing trades by account requires an operator token that the app does not have.
Trade states, in order: queued → processing / received → awaiting_vault_payout (sell) → orders_placed → partial → filled or reclaimed → settled (buy) or returned (sell). unknown means the relay has never seen the note.
Limits: 10 trade posts per minute per IP, 6 re-posts of the same note per minute, trade body ≤ 96 KiB. A buy over a beta cap is still accepted by the relay once sent; the app refuses it before you sign, because by the time it reaches the relay your USDCx is already on its way.
The full relay contract is in darwin-relay/server/API.md.
Chain helpers
| Route | Returns |
|---|---|
GET /api/note-status?id= | Whether a note is committed. Used to confirm your send landed before handing it to the relay |
GET /api/network-note-status?id= | What the network did with a network note |
POST /api/nullifier-status | Which of a set of notes are already consumed |
GET /api/miden-block | The chain tip |
GET /api/account-notes?tag= | Note ids created with a tag in a block window |
Retired
POST /api/network-note, the older server-built note rail, returns 410. Notes are built in the browser.