# Agent Wallet Setup

After authenticating and obtaining a set of tokens, the next step is to ensure that Pear Protocol can perform actions on the Hyperliquid Exchange on behalf of the user.

We are using the [API / Agent Wallet](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/nonces-and-api-wallets) provided by Hyperliquid. Each **Single Agent Wallet** is used exclusively by one user, and its private key is securely stored and encrypted within the Pear Protocol system. An Agent Wallet remains valid for 180 days, but it will be rotated every 30 days.

{% @mermaid/diagram content="sequenceDiagram
participant User
participant PearProtocol as Pear Protocol
participant HyperliquidAPI as Hyperliquid API
participant UserWallet as User's Wallet
User->>PearProtocol: Request to integrate with Hyperliquid
Note over PearProtocol: Step 1: Check Agent Wallet
PearProtocol->>HyperliquidAPI: GET Agent Wallet
HyperliquidAPI-->>PearProtocol: Response (status: NOT FOUND/ACTIVE/EXPIRED)
alt Status: ACTIVE
Note over PearProtocol: Existing wallet can be used
PearProtocol->>PearProtocol: Use existing Agent Wallet
else Status: NOT FOUND or EXPIRED
Note over PearProtocol: Step 2: Create Agent Wallet
PearProtocol->>HyperliquidAPI: Create Agent Wallet
HyperliquidAPI-->>PearProtocol: New Agent Wallet address
Note over PearProtocol: Step 3: Prompt User Approval
PearProtocol->>User: Request Agent Wallet approval
User->>UserWallet: Sign authorization message
UserWallet-->>User: Signed message
User->>HyperliquidAPI: Submit Agent Wallet approval directly
HyperliquidAPI-->>User: Approval confirmation
end
Note over PearProtocol: Step 4: Use Agent Wallet
PearProtocol->>HyperliquidAPI: Perform trading actions using Agent Wallet
HyperliquidAPI-->>PearProtocol: Trading results
PearProtocol-->>User: Integration complete, ready for trading
Note over PearProtocol: Agent Wallet Valid for 180 days" %}

Below is the step-by-step guide to integrate Pear Protocol with the Hyperliquid Exchange using an Agent Wallet:

1. **Check Agent Wallet** – Before creating a new Agent Wallet, check whether the user already has one by calling the `GET Agent Wallet` endpoint. The response will include the Agent Wallet address and status:
   * If the status is `NOT FOUND`, it means no wallet has been created.
   * If the status is `ACTIVE`, the existing Agent Wallet can be used.
   * If the status is `EXPIRED`, proceed to step 3 to prompt the user to approve a new Agent Wallet.
2. **Create Agent Wallet** – If no wallet exists or it has expired, Pear Protocol will create a new Agent Wallet for the user by calling the `Create Agent Wallet` endpoint. The response will include the new Agent Wallet address.
3. **Prompt the User to Approve the Agent Wallet** – Once the wallet is created, prompt the user to approve it. This requires the user to sign a message using their own wallet, authorizing Pear Protocol to use the Agent Wallet on their behalf. More details can be found in the [Agent Wallet Approval](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/nonces-and-api-wallets#agent-wallet-approval) section of the documentation.
4. **Use the Agent Wallet** – After the user has approved the Agent Wallet, Pear Protocol can use it to interact with the Hyperliquid Exchange on behalf of the user.


---

# 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/access-management/agent-wallet-setup.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.