Authentication Process

Authentication

Pear Protocol uses EIP-712 wallet signature authentication combined with JWT tokens. No passwords required — wallet ownership is the identity.

Authentication Flow

Step 1: EIP-712 Authentication

Request an EIP-712 message via GET /auth/eip712-message with your address and clientId, sign it with your wallet, then send the signature to POST /auth/authenticate:

{
  "method": "eip712",
  "address": "0x1234...5678",
  "clientId": "YOUR_CLIENT_ID",
  "details": {
    "signature": "0xabcdef...",
    "timestamp": 1703872800
  }
}

On success, the server returns JWT tokens:

Token	Default Expiry
Access token	15 minutes
Refresh token	30 days

Step 2: Generate API Key

Using the access token from step 1, create an API key:

POST /api-keys

{
  "name": "Trading Bot Key"
}

Response:

{
  "id": "key-id",
  "apiKey": "your-api-key-value",
  "name": "Trading Bot Key",
  "createdAt": "2025-05-15T10:00:00.000Z"
}

Store the apiKey value immediately — it is only returned once at creation time.

Step 3: Authenticate with API Key

From now on, use the stored API key to get JWT tokens — no wallet interaction needed:

POST /auth/authenticate

{
  "method": "api_key",
  "address": "0x1234...5678",
  "clientId": "YOUR_CLIENT_ID",
  "details": {
    "apiKey": "your-api-key-value"
  }
}

This returns JWT tokens. Use the access token in all requests:

Authorization: Bearer <access_token>

Client ID

clientId is required in all authentication requests (EIP-712 and API key).

• Individual traders: use APITRADER.

• Products built on top of the API: contact us to obtain your own Client ID. This lets us track usage and provide partner-specific features.

Refresh Token

When the access token expires, call POST /auth/refresh with the refresh token to get a new access token without signing again.

Logout

Call POST /auth/logout with the refresh token to invalidate the session server-side.