Authentication

The V3 gateway accepts three authentication transports. Pick the one that matches your integration:

Every account-scoped request also sends the trade-account header:

x-trade-account-id: <trade-account-id>

This selects which connected exchange account the call reads from or trades on (see Trade Accounts).

API key (server-side)

For a server-side integration, mint an API key once and send it on every request.

1. Sign in as a user (wallet or email, below) to get a session.
2. Create a key: POST /api-keys. The response returns the raw key once, store it in a secret manager.
3. Send x-api-key: <key> on each gateway request. Check the key's identity any time with GET /auth/api-key/me.

List keys with GET /api-keys; revoke one with DELETE /api-keys/:id. An unknown, expired, or revoked key returns 401.

Wallet login

Wallet ownership is the identity, no password.

1. Request a nonce: POST /auth/nonce with { "address": "0x…" } → returns a message to sign.
2. Sign the message with the wallet.
3. Log in: POST /auth/login

{
  "method": "wallet",
  "address": "0x…",
  "signature": "0x…"
}

The response returns an access token (and sets a session cookie). Send the access token as Authorization: Bearer <access-token>, or rely on the cookie in session mode.

Single-flight the nonce → login step: concurrent nonce requests rotate the nonce and will 401 the earlier signature.

Email login

Register with POST /auth/register/emailpass (sends a verification email), verify via POST /auth/verify-email, then POST /auth/login with { "method": "email", … }. Password reset runs POST /auth/password/forgot → POST /auth/password/reset.

OAuth 2.0 (delegated)

For agents and third-party apps acting on a user's behalf, use the OAuth 2.0 authorization-code flow with PKCE. The user signs in and approves access on a Pear-hosted page; your app never sees their credentials. This is what the Orchard MCP uses, see the Pear MCP integration guide for the complete flow.

Client ID (attribution)

Send your Pear-issued client ID so trading volume routed through your integration is attributed to you. In the SDK it's clientId; it rides with trade / trigger / schedule / rebalance calls. It's validated server-side (exact, case-sensitive), an unknown or inactive code is rejected. Contact Pear to get a client ID.

Refresh & logout

• Refresh, session cookie: POST /auth/session/refresh; bearer token: POST /auth/session/refresh/token (refresh token in the body).
• Current user, GET /auth/session/me.
• Logout, POST /auth/session/logout invalidates the session server-side.

See Trade Accounts for how to connect an exchange and scope requests.