# Authentication

## Authenticate user

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

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"paths":{"/auth/login":{"post":{"description":"Authenticate a user using EIP712 signature or API key and return access/refresh tokens","operationId":"AuthController_authenticate","parameters":[],"requestBody":{"required":true,"description":"Authentication request with EIP712 signature or API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticateRequestDto"}}}},"responses":{"200":{"description":"Authentication successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticateResponseDto"}}}},"400":{"description":"Bad request - invalid input data"},"401":{"description":"Unauthorized - authentication failed"}},"summary":"Authenticate user","tags":["Authentication"]}}},"components":{"schemas":{"AuthenticateRequestDto":{"type":"object","properties":{"method":{"type":"string","description":"Authentication method","enum":["eip712","api_key","privy_access_token"]},"address":{"type":"string","description":"User wallet address","pattern":"^0x[a-fA-F0-9]{40}$"},"clientId":{"type":"string","description":"Client identifier"},"details":{"description":"Authentication method specific details","oneOf":[{"$ref":"#/components/schemas/EIP712AuthDetailsDto"},{"$ref":"#/components/schemas/ApiKeyAuthDetailsDto"},{"$ref":"#/components/schemas/PrivyAuthDetailsDto"}]}},"required":["method","address","clientId","details"]},"EIP712AuthDetailsDto":{"type":"object","properties":{"signature":{"type":"string","description":"EIP712 signature"},"timestamp":{"type":"number","description":"Unix timestamp used in the signed message"},"chainId":{"type":"number","description":"EIP-155 chain ID used in the EIP712 domain when signing. Optional; falls back to server default (EIP712_CHAIN_ID) for backward compatibility."}},"required":["signature","timestamp"]},"ApiKeyAuthDetailsDto":{"type":"object","properties":{"apiKey":{"type":"string","description":"API key for authentication"}},"required":["apiKey"]},"PrivyAuthDetailsDto":{"type":"object","properties":{"appId":{"type":"string","description":"Privy App ID"},"accessToken":{"type":"string","description":"Privy access token (JWT)"}},"required":["appId","accessToken"]},"AuthenticateResponseDto":{"type":"object","properties":{"accessToken":{"type":"string","description":"JWT access token"},"refreshToken":{"type":"string","description":"Refresh token for obtaining new access tokens"},"tokenType":{"type":"string","description":"Token type"},"expiresIn":{"type":"number","description":"Token expiration time in seconds"},"address":{"type":"string","description":"User wallet address"},"clientId":{"type":"string","description":"Client identifier"}},"required":["accessToken","refreshToken","tokenType","expiresIn","address","clientId"]}}}}
```

## Get EIP712 message to sign

> Generate EIP712 structured data for client-side signing

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"paths":{"/auth/eip712-message":{"get":{"description":"Generate EIP712 structured data for client-side signing","operationId":"AuthController_getEIP712Message","parameters":[{"name":"address","required":true,"in":"query","description":"User wallet address","schema":{"type":"string"}},{"name":"clientId","required":true,"in":"query","description":"Client identifier","schema":{"type":"string"}},{"name":"chainId","required":true,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"EIP712 message generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetEIP712MessageResponseDto"}}}},"400":{"description":"Bad request - invalid parameters"}},"summary":"Get EIP712 message to sign","tags":["Authentication"]}}},"components":{"schemas":{"GetEIP712MessageResponseDto":{"type":"object","properties":{"domain":{"type":"object","description":"EIP712 domain"},"types":{"type":"object","description":"EIP712 types"},"primaryType":{"type":"string","description":"Primary type for EIP712 signing"},"message":{"type":"object","description":"Message to sign"},"timestamp":{"type":"number","description":"Unix timestamp used in message"}},"required":["domain","types","primaryType","message","timestamp"]}}}}
```

## Refresh access token

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

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"paths":{"/auth/refresh":{"post":{"description":"Use a valid refresh token to obtain a new access token and refresh token","operationId":"AuthController_refreshToken","parameters":[],"requestBody":{"required":true,"description":"Refresh token request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequestDto"}}}},"responses":{"200":{"description":"Token refresh successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenResponseDto"}}}},"401":{"description":"Unauthorized - invalid or expired refresh token"}},"summary":"Refresh access token","tags":["Authentication"]}}},"components":{"schemas":{"RefreshTokenRequestDto":{"type":"object","properties":{"refreshToken":{"type":"string","description":"Refresh token"}},"required":["refreshToken"]},"RefreshTokenResponseDto":{"type":"object","properties":{"accessToken":{"type":"string","description":"New JWT access token"},"refreshToken":{"type":"string","description":"New refresh token"},"tokenType":{"type":"string","description":"Token type"},"expiresIn":{"type":"number","description":"Token expiration time in seconds"}},"required":["accessToken","refreshToken","tokenType","expiresIn"]}}}}
```

## Logout user

> Invalidate refresh token and log out the user

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"paths":{"/auth/logout":{"post":{"description":"Invalidate refresh token and log out the user","operationId":"AuthController_logout","parameters":[],"requestBody":{"required":true,"description":"Logout request with refresh token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogoutRequestDto"}}}},"responses":{"200":{"description":"Logout successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogoutResponseDto"}}}},"401":{"description":"Unauthorized - invalid refresh token"}},"summary":"Logout user","tags":["Authentication"]}}},"components":{"schemas":{"LogoutRequestDto":{"type":"object","properties":{"refreshToken":{"type":"string","description":"Refresh token to invalidate"}},"required":["refreshToken"]},"LogoutResponseDto":{"type":"object","properties":{"message":{"type":"string","description":"Logout status message"}},"required":["message"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pearprotocol.io/api-integration/api-specification/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.