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>

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 (login optional):

POST /api/maker/applications

{
  "organization_name": "Example Desk",
  "contact_name": "Ada",
  "email": "ada@example.com",
  "website": "https://example.com",
  "wallet_address": "0x…",
  "notes": "optional"
}

The trading app form is at /makers. 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.

Who needs auth?

Action	Auth
Create options quote	No
Apply as maker	No (token optional)
Poll quote with stream token	Stream token (header or query)
Read portfolio / networks / bond requirements	No
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)