Skip to content

Get API access

All three Edith APIs — Photon, Vector, and Meadow — authenticate with the same mechanism: an API key sent in the api-key header of every request.

curl https://photon.example.com/api/user?address=0xYourAddress \
  -H "api-key: $EDITH_API_KEY"

Info

The hostnames in these docs (photon.example.com, vector.example.com, meadow.example.com) are placeholders — use the base URLs you were given with your API key.

API keys

API keys are issued by the platform operator. Request one through your Edith contact; you'll receive:

  • your key (a tk_… token — treat it as a secret),
  • the base URLs for the three services,
  • a prepaid USD balance on your account. Photon charges each relayed transaction's cost against this balance; see Core concepts for how balances, per-transaction limits, and daily limits work.

Send the key on every request. Requests without a valid key are rejected with 401 — Photon and Meadow return the error envelope with an AUTH code, Vector returns {"code": 401, "message": "missing api-key header", "data": null}.

Wallet login (JWT)

Photon's account-management endpoints — Register webhooks and Register WebSocket credential — also accept a Bearer JWT obtained by proving control of your wallet address. No pre-issued key is needed for this flow:

  1. POST /api/auth/message with your address — returns a message and a messageId (valid for 5 minutes).
  2. Sign the message with your wallet (EIP-191 personal_sign).
  3. POST /api/auth/verify with the messageId and signature — returns a JWT.
curl -X POST https://photon.example.com/api/auth/message \
  -H "Content-Type: application/json" \
  -d '{"address": "0xYourAddress"}'
# sign data.message with your wallet, then:
curl -X POST https://photon.example.com/api/auth/verify \
  -H "Content-Type: application/json" \
  -d '{"messageId": "…", "signature": "0x…"}'

Use the token as Authorization: Bearer <token> on the register endpoints. Signature failures map to AUTH_006 (bad nonce), AUTH_007 (expired), and AUTH_008 (invalid signature) — see Error codes.

Which credential where

Endpoint group Credential
Photon submit / quote api-key
Photon register-webhooks / register-websocket api-key or Bearer JWT
Photon status / account / chains / health none (public)
Photon WebSocket (/ws) x-ws-token from Register WebSocket credential
Vector — all endpoints api-key
Meadow — quotes, deposits, withdrawals, orders, positions, earnings api-key
Meadow discovery (chains, assets, venues, rates) none (public)

Ready to make your first call? Start with the Photon quickstart.