> For the complete documentation index, see [llms.txt](https://docs.pearprotocol.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pearprotocol.io/api-integration/access-management/agent-wallet-setup.md).

# 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.