# Vault Wallet

## Get vault wallet

> Retrieve a specific vault wallet by address (agent\_address or vault\_address)

```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)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"GetVaultWalletResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the vault wallet"},"vaultAddress":{"type":"object","description":"Vault wallet address"},"leader_address":{"type":"string","description":"Vault wallet address"},"agentAddress":{"type":"string","description":"Public address"},"isApproved":{"type":"boolean","description":"Whether the vault wallet is approved for trading"},"createdAt":{"type":"string","description":"Timestamp when the vault wallet was created"},"updatedAt":{"type":"string","description":"Timestamp when the vault wallet was last updated"},"privyWalletId":{"type":"string","description":"Privy wallet ID for creating the signer"},"name":{"type":"object","description":"Vault wallet name","nullable":true},"about":{"type":"object","description":"Vault wallet description/about","nullable":true},"imageUrl":{"type":"object","description":"Image URL for the vault wallet","nullable":true},"transactionHash":{"type":"object","description":"Transaction hash from vault creation","nullable":true}},"required":["id","vaultAddress","leader_address","agentAddress","isApproved","createdAt","updatedAt","privyWalletId"]}}},"paths":{"/vault-wallet":{"get":{"description":"Retrieve a specific vault wallet by address (agent_address or vault_address)","operationId":"VaultWalletController_getVaultWallet","parameters":[{"name":"vaultAddress","required":true,"in":"query","description":"Vault address - can be agent_address (Privy wallet) or vault_address (contract)","schema":{"type":"string"}}],"responses":{"200":{"description":"Vault wallet retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetVaultWalletResponseDto"}}}},"401":{"description":"Unauthorized - invalid or missing token"},"404":{"description":"Vault wallet not found"}},"summary":"Get vault wallet","tags":["Vault Wallet"]}}}}
```

## Create a new vault wallet with onchain deployment

> This API performs all vault creation steps in one call: 1) Creates a Privy wallet (agent), 2) Deploys vault contract via PearVaultFactory onchain, 3) Saves to database, 4) Creates backend agent wallet for trading. This replaces the old two-step process (createVaultWallet + registerVault).

```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)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"CreateVaultWalletRequestDto":{"type":"object","properties":{"leader_address":{"type":"string","description":"Leader/owner address of the vault"},"name":{"type":"string","description":"Name for the vault wallet"},"about":{"type":"string","description":"Description/about text for the vault wallet"},"imageUrl":{"type":"string","description":"Image URL for the vault wallet"},"configId":{"type":"number","description":"Configuration ID for the vault from frontend (0-based index)","minimum":0}},"required":["leader_address","name","imageUrl","configId"]},"CreateVaultWalletResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the vault wallet"},"leader_address":{"type":"string","description":"Leader/owner address"},"vaultAddress":{"type":"string","description":"Generated vault contract address from blockchain"},"agentAddress":{"type":"string","description":"Privy agent wallet address"},"isApproved":{"type":"boolean","description":"Whether the vault wallet is approved for trading"},"name":{"type":"string","description":"Vault wallet name"},"about":{"type":"string","description":"Vault wallet description/about"},"imageUrl":{"type":"string","description":"Image URL for the vault wallet"},"transactionHash":{"type":"string","description":"Transaction hash from vault creation"},"createdAt":{"type":"string","description":"Timestamp when the vault wallet was created"},"message":{"type":"string","description":"Success message"}},"required":["id","leader_address","vaultAddress","agentAddress","isApproved","name","about","imageUrl","transactionHash","createdAt","message"]}}},"paths":{"/vault-wallet":{"post":{"description":"This API performs all vault creation steps in one call: 1) Creates a Privy wallet (agent), 2) Deploys vault contract via PearVaultFactory onchain, 3) Saves to database, 4) Creates backend agent wallet for trading. This replaces the old two-step process (createVaultWallet + registerVault).","operationId":"VaultWalletController_createVaultWallet","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVaultWalletRequestDto"}}}},"responses":{"201":{"description":"Vault created successfully with onchain transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVaultWalletResponseDto"}}}},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid or missing token"},"500":{"description":"Failed to create vault (Privy wallet creation or blockchain transaction failed)"}},"summary":"Create a new vault wallet with onchain deployment","tags":["Vault Wallet"]}}}}
```

## Delete vault wallet

> Delete a specific vault wallet by address. This action cannot be undone.

```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)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}}},"paths":{"/vault-wallet":{"delete":{"description":"Delete a specific vault wallet by address. This action cannot be undone.","operationId":"VaultWalletController_deleteVaultWallet","parameters":[{"name":"vaultAddress","required":true,"in":"query","description":"Vault address - can be agent_address (Privy wallet) or vault_address (contract)","schema":{"type":"string"}}],"responses":{"204":{"description":"Vault wallet deleted successfully"},"401":{"description":"Unauthorized - invalid or missing token"},"404":{"description":"Vault wallet not found"}},"summary":"Delete vault wallet","tags":["Vault Wallet"]}}}}
```

## Get all vault wallets

> Retrieve all vault wallets for the authenticated user. Supports filtering by name and address.

```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)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"GetVaultWalletResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the vault wallet"},"vaultAddress":{"type":"object","description":"Vault wallet address"},"leader_address":{"type":"string","description":"Vault wallet address"},"agentAddress":{"type":"string","description":"Public address"},"isApproved":{"type":"boolean","description":"Whether the vault wallet is approved for trading"},"createdAt":{"type":"string","description":"Timestamp when the vault wallet was created"},"updatedAt":{"type":"string","description":"Timestamp when the vault wallet was last updated"},"privyWalletId":{"type":"string","description":"Privy wallet ID for creating the signer"},"name":{"type":"object","description":"Vault wallet name","nullable":true},"about":{"type":"object","description":"Vault wallet description/about","nullable":true},"imageUrl":{"type":"object","description":"Image URL for the vault wallet","nullable":true},"transactionHash":{"type":"object","description":"Transaction hash from vault creation","nullable":true}},"required":["id","vaultAddress","leader_address","agentAddress","isApproved","createdAt","updatedAt","privyWalletId"]}}},"paths":{"/vault-wallet/all":{"get":{"description":"Retrieve all vault wallets for the authenticated user. Supports filtering by name and address.","operationId":"VaultWalletController_getAllVaultWallets","parameters":[{"name":"name","required":false,"in":"query","description":"Filter vault wallets by name (case-insensitive partial match)","schema":{"type":"string"}},{"name":"address","required":false,"in":"query","description":"Filter vault wallets by address (matches agent_address or vault_address, case-insensitive partial match)","schema":{"type":"string"}}],"responses":{"200":{"description":"Vault wallets retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GetVaultWalletResponseDto"}}}}},"401":{"description":"Unauthorized - invalid or missing token"}},"summary":"Get all vault wallets","tags":["Vault Wallet"]}}}}
```

## Refresh agent wallet for vault

> Create a new agent wallet for a specific registered vault. This is useful when the current agent wallet needs to be refreshed or rotated.

```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)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"RefreshApiForVaultResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the vault wallet"},"leader_address":{"type":"string","description":"Owner wallet address"},"vaultAddress":{"type":"string","description":"Vault contract address"},"newAgentWalletAddress":{"type":"string","description":"New agent wallet address for backend trading"},"message":{"type":"string","description":"Success message"}},"required":["id","leader_address","vaultAddress","newAgentWalletAddress","message"]}}},"paths":{"/vault-wallet/refreshAPIforVault":{"post":{"description":"Create a new agent wallet for a specific registered vault. This is useful when the current agent wallet needs to be refreshed or rotated.","operationId":"VaultWalletController_refreshApiForVault","parameters":[{"name":"vaultAddress","required":true,"in":"query","description":"Vault address - can be agent_address (Privy wallet) or vault_address (contract)","schema":{"type":"string"}}],"responses":{"200":{"description":"Agent wallet refreshed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshApiForVaultResponseDto"}}}},"401":{"description":"Unauthorized - invalid or missing token"},"404":{"description":"Vault wallet not found or vault not registered"}},"summary":"Refresh agent wallet for vault","tags":["Vault Wallet"]}}}}
```

## Transfer USDC from spot to perp account

> Transfer USDC directly from spot account to perp account for trading

```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)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"TransferSpotToPerpRequestDto":{"type":"object","properties":{"amount":{"type":"string","description":"Amount of USDC to transfer from spot to perp account","minimum":0.01},"asset":{"type":"string","description":"Asset to transfer (default: USDC)","default":"USDC"}},"required":["amount"]},"TransferResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Transfer success status"},"amount":{"type":"string","description":"Amount transferred"},"asset":{"type":"string","description":"Asset transferred"},"direction":{"type":"string","description":"Transfer direction"},"message":{"type":"string","description":"Success message"}},"required":["success","amount","asset","direction","message"]}}},"paths":{"/vault-wallet/spot-to-perp":{"post":{"description":"Transfer USDC directly from spot account to perp account for trading","operationId":"VaultWalletController_transferSpotToPerp","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferSpotToPerpRequestDto"}}}},"responses":{"200":{"description":"Transfer completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferResponseDto"}}}},"400":{"description":"Invalid transfer amount or insufficient balance"},"401":{"description":"Unauthorized - invalid or missing token"}},"summary":"Transfer USDC from spot to perp account","tags":["Vault Wallet"]}}}}
```

## Transfer USDC from perp to spot account

> Transfer USDC directly from perp account to spot account

```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)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"TransferPerpToSpotRequestDto":{"type":"object","properties":{"amount":{"type":"string","description":"Amount of USDC to transfer from perp to spot account","minimum":0.01},"asset":{"type":"string","description":"Asset to transfer (default: USDC)","default":"USDC"}},"required":["amount"]},"TransferResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Transfer success status"},"amount":{"type":"string","description":"Amount transferred"},"asset":{"type":"string","description":"Asset transferred"},"direction":{"type":"string","description":"Transfer direction"},"message":{"type":"string","description":"Success message"}},"required":["success","amount","asset","direction","message"]}}},"paths":{"/vault-wallet/perp-to-spot":{"post":{"description":"Transfer USDC directly from perp account to spot account","operationId":"VaultWalletController_transferPerpToSpot","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferPerpToSpotRequestDto"}}}},"responses":{"200":{"description":"Transfer completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferResponseDto"}}}},"400":{"description":"Invalid transfer amount or insufficient balance"},"401":{"description":"Unauthorized - invalid or missing token"}},"summary":"Transfer USDC from perp to spot account","tags":["Vault Wallet"]}}}}
```

## Swap spot token to USDC and transfer to perp

> Swap a spot token (ETH, SOL, etc.) to USDC and transfer the USDC to perp account for trading

```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)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"SwapAndTransferRequestDto":{"type":"object","properties":{"fromAsset":{"type":"string","description":"Asset to swap from (e.g., ETH, SOL, BTC)"},"amount":{"type":"string","description":"Amount of the source asset to swap","minimum":0.001},"toAsset":{"type":"string","description":"Asset to swap to (default: USDC)","default":"USDC"}},"required":["fromAsset","amount"]},"SwapAndTransferResponseDto":{"type":"object","properties":{"fromAmount":{"type":"string","description":"Amount of source asset swapped"},"toAmount":{"type":"string","description":"Amount of target asset received"},"exchangeRate":{"type":"number","description":"Exchange rate used"},"fromAsset":{"type":"string","description":"Source asset"},"toAsset":{"type":"string","description":"Target asset"},"message":{"type":"string","description":"Success message"}},"required":["fromAmount","toAmount","exchangeRate","fromAsset","toAsset","message"]}}},"paths":{"/vault-wallet/swap-and-transfer":{"post":{"description":"Swap a spot token (ETH, SOL, etc.) to USDC and transfer the USDC to perp account for trading","operationId":"VaultWalletController_swapAndTransferToPerp","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapAndTransferRequestDto"}}}},"responses":{"200":{"description":"Swap and transfer completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapAndTransferResponseDto"}}}},"400":{"description":"Invalid swap parameters or insufficient balance"},"401":{"description":"Unauthorized - invalid or missing token"}},"summary":"Swap spot token to USDC and transfer to perp","tags":["Vault Wallet"]}}}}
```

## Get spot and perp account balances

> Retrieve balances for both spot and perp accounts

```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)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"GetBalancesResponseDto":{"type":"object","properties":{"spotBalances":{"type":"object","description":"Spot account balances"},"perpBalances":{"type":"object","description":"Perp account balances"},"totalValue":{"type":"string","description":"Total account value in USD"}},"required":["spotBalances","perpBalances","totalValue"]}}},"paths":{"/vault-wallet/balances":{"get":{"description":"Retrieve balances for both spot and perp accounts","operationId":"VaultWalletController_getBalances","parameters":[],"responses":{"200":{"description":"Balances retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetBalancesResponseDto"}}}},"401":{"description":"Unauthorized - invalid or missing token"}},"summary":"Get spot and perp account balances","tags":["Vault Wallet"]}}}}
```


---

# 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/vault-wallet.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.