Authentication

Authenticate user

post

Authenticate a user using EIP712 signature or API key and return access/refresh tokens

Body

application/json

methodstring · enumRequired

Authentication method

Example: eip712Possible values:

addressstringRequired

User wallet address

Example: 0x1234567890123456789012345678901234567890Pattern: ^0x[a-fA-F0-9]{40}$

clientIdstringRequired

Client identifier

Example: phantom-exchange

detailsone ofRequired

Authentication method specific details

or

Responses

200

Authentication successful

application/json

accessTokenstringRequired

JWT access token

Example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

refreshTokenstringRequired

Refresh token for obtaining new access tokens

Example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

tokenTypestringRequired

Token type

Example: Bearer

expiresInnumberRequired

Token expiration time in seconds

Example: 900

addressstringRequired

User wallet address

Example: 0x1234567890123456789012345678901234567890

clientIdstringRequired

Client identifier

Example: phantom-exchange

400

Bad request - invalid input data

401

Unauthorized - authentication failed

post

/auth/login

HTTPcURLJavaScriptPython

POST /auth/login HTTP/1.1
Host: hl-v2.pearprotocol.io
Content-Type: application/json
Accept: */*
Content-Length: 175

{
  "method": "eip712",
  "address": "0x1234567890123456789012345678901234567890",
  "clientId": "phantom-exchange",
  "details": {
    "signature": "0x1234567890abcdef...",
    "timestamp": 1703872800
  }
}

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "address": "0x1234567890123456789012345678901234567890",
  "clientId": "phantom-exchange"
}

Get EIP712 message to sign

get

Generate EIP712 structured data for client-side signing

Query parameters

addressstringRequired

User wallet address

Example: 0x1234567890123456789012345678901234567890

clientIdstringRequired

Client identifier

Example: phantom-exchange

Responses

200

EIP712 message generated successfully

application/json

domainobjectRequired

EIP712 domain

Example: {"name":"Pear Protocol","version":"1","chainId":1,"verifyingContract":"0x0000000000000000000000000000000000000000"}

typesobjectRequired

EIP712 types

Example: {"Authentication":[{"name":"address","type":"address"},{"name":"clientId","type":"string"},{"name":"timestamp","type":"uint256"},{"name":"action","type":"string"}]}

primaryTypestringRequired

Primary type for EIP712 signing

Example: Authentication

messageobjectRequired

Message to sign

Example: {"address":"0x1234567890123456789012345678901234567890","clientId":"phantom-exchange","timestamp":1703872800,"action":"authenticate"}

timestampnumberRequired

Unix timestamp used in message

Example: 1703872800

400

Bad request - invalid parameters

get

/auth/eip712-message

HTTPcURLJavaScriptPython

GET /auth/eip712-message?address=0x1234567890123456789012345678901234567890&clientId=phantom-exchange HTTP/1.1
Host: hl-v2.pearprotocol.io
Accept: */*

{
  "domain": {
    "name": "Pear Protocol",
    "version": "1",
    "chainId": 1,
    "verifyingContract": "0x0000000000000000000000000000000000000000"
  },
  "types": {
    "Authentication": [
      {
        "name": "address",
        "type": "address"
      },
      {
        "name": "clientId",
        "type": "string"
      },
      {
        "name": "timestamp",
        "type": "uint256"
      },
      {
        "name": "action",
        "type": "string"
      }
    ]
  },
  "primaryType": "Authentication",
  "message": {
    "address": "0x1234567890123456789012345678901234567890",
    "clientId": "phantom-exchange",
    "timestamp": 1703872800,
    "action": "authenticate"
  },
  "timestamp": 1703872800
}

Refresh access token

post

Use a valid refresh token to obtain a new access token and refresh token

Body

application/json

refreshTokenstringRequired

Refresh token

Example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Responses

200

Token refresh successful

application/json

accessTokenstringRequired

New JWT access token

Example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

refreshTokenstringRequired

New refresh token

Example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

tokenTypestringRequired

Token type

Example: Bearer

expiresInnumberRequired

Token expiration time in seconds

Example: 900

401

Unauthorized - invalid or expired refresh token

post

/auth/refresh

HTTPcURLJavaScriptPython

POST /auth/refresh HTTP/1.1
Host: hl-v2.pearprotocol.io
Content-Type: application/json
Accept: */*
Content-Length: 58

{
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 900
}

Logout user

post

Invalidate refresh token and log out the user

Body

application/json

refreshTokenstringRequired

Refresh token to invalidate

Example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Responses

200

Logout successful

application/json

messagestringRequired

Logout status message

Example: Successfully logged out

401

Unauthorized - invalid refresh token

post

/auth/logout

HTTPcURLJavaScriptPython

POST /auth/logout HTTP/1.1
Host: hl-v2.pearprotocol.io
Content-Type: application/json
Accept: */*
Content-Length: 58

{
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

{
  "message": "Successfully logged out"
}