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)

RouteReturns
GET /api/price/BLUEDWNAV 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/pricesCoin prices from Pragma, falling back to CoinGecko only if the oracle is stale
GET /api/pragma-pricesPragma'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 routeRelay routeDoes
POST /api/relay-depositPOST /relay/depositHands the relay your buy note file
POST /api/relay-redeemPOST /relay/redeemHands the relay your sell note file
GET /api/relay-status?note=GET /relay/statusA trade's state and step. Details only with a view proof
GET/POST /api/relay-shares/relay/sharesFetch and acknowledge your share note (proof required)
GET/POST /api/relay-returns/relay/returnsFetch and acknowledge your sell's USDCx note (proof required)
POST /api/relay-lookupPOST /relay/lookupYour trades, by {note, proof} pairs. Only notes whose proof verifies come back
GET /api/relay-healthGET /healthRelay 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

RouteReturns
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-statusWhich of a set of notes are already consumed
GET /api/miden-blockThe 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.