Authentication (SIWE)

Most maker actions need either:

1. A SIWE bearer token from wallet login, or
2. A maker API key issued by a maker organization admin

Both are sent as:

Authorization: Bearer <token>

With @opshuns/sdk: client.loginWithSiwe(address, signFn) stores the bearer on the client; maker keys go in startMakerSession({ apiKey }). Guide: TypeScript SDK.

SIWE login flow

1. Fetch a nonce

GET /api/login/nonce

{
  "nonce": "random-string",
  "domain": "localhost:4000",
  "uri": "http://localhost:4000",
  "chain_id": 31337,
  "statement": "Sign in to the Opshuns API",
  "version": "1",
  "issued_at": "2026-07-10T06:00:00Z",
  "expiration_time": "2026-07-17T06:00:00Z"
}

Build an EIP-4361 message that includes all of these fields (including issued_at and expiration_time). Expired messages are rejected.

2. Sign and exchange

POST /api/login

{
  "message": "<full SIWE message string>",
  "signature": "0x..."
}

Response

{
  "token": "phoenix-signed-bearer-token",
  "address": "0x...",
  "expires_in": 604800
}

3. Check session

GET /api/me with the bearer token.

Freemium / plain wallet:

{ "address": "0x...", "tier": "freemium" }

Maker organization admin, owner, manager, or member:

{
  "address": "0x...",
  "tier": "maker",
  "role": "owner",
  "organization_id": "...",
  "organization_name": "..."
}

role is one of admin | owner | manager | member. Owners and managers can issue keys and transfer admin, same as admin.

Apply as a maker

No maker rights yet? Submit an application from the trading app at /makers (Web3Forms intake: not an Opshuns API route). A system admin still has to create the org before GET /api/me returns tier: "maker".

Maker API keys

Organization admins / owners / managers can issue keys for bot wallets:

• GET /api/maker/keys
• POST /api/maker/keys: body includes address, name, and a wallet message + signature from the org admin
• DELETE /api/maker/keys/:id: body includes the admin message + signature
• PUT /api/maker/organization: transfer org admin (Action: transfer_admin)

Add, remove, and transfer are signed admin actions. The admin wallet personal_signs a plaintext statement:

Opshuns maker admin action

Action: add_member
Admin: 0x…
Member: 0x…
Organization: …
Name: bot-1
Issued At: 2026-08-11T14:00:00Z

Actions: add_member, remove_member, transfer_admin. The API recovers the signer and requires it to be the org owner/manager.

Keys authenticate REST (Authorization: Bearer <secret>) and WebSocket joins (api_key query/param on private maker channels).

See Become a market maker for the org / key model.

Taker org API keys & delegates

Taker organizations (wallet / backend integrators) use /api/taker/* with the org admin wallet or long-lived API keys. See Add to your crypto wallet (API taker).

Action	Auth
Manage taker keys	Taker admin SIWE
POST /api/taker/delegate	Taker API key or taker admin SIWE + signature

Delegate JWTs minted with a taker API key skip Turnstile on POST /api/quote and can access explore / loan-data routes. Delegates minted from the taker admin UI (wallet-signed) skip Turnstile on quote create but are rejected on explore.

Explore & loan data (Explore gate)

CLOB analytics and loan explorer routes require the Explore gate: not a maker key and not a raw taker API key:

(SIWE ∧ Turnstile + allowed Origin) ∨ taker-delegate JWT (API-key mint only)

The trading app (/explore, /loan-explorer) uses the website path: SIWE bearer + browser Origin + Turnstile when enforced. Full route list, WebSocket mint, and integrator flow: Explore & loan data auth.

Who needs auth?

Action	Auth
Create options quote	No (Turnstile or taker-delegate JWT when enforced)
Apply as maker	No (third-party form on /makers)
Poll quote with stream token	Stream token (header or query)
Read portfolio / networks / bond requirements	No
Explore CLOB / loan analytics	Explore gate. detail
Post maker offer / exclusive fill	Yes (maker rights)
Register premium pubsub	Yes (maker rights)
Manage maker keys / transfer admin	Yes (org owner/manager) + wallet signature
Create Borrow quote / lender offer / borrower select	Coming soon (planned: create public; offer maker-auth; select borrower-auth)