# Vault Wallet

## Get vault wallet

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

```json
{"openapi":"3.0.3","info":{"title":"Pear Protocol Trading API","version":"3.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.3","info":{"title":"Pear Protocol Trading API","version":"3.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.3","info":{"title":"Pear Protocol Trading API","version":"3.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.3","info":{"title":"Pear Protocol Trading API","version":"3.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.3","info":{"title":"Pear Protocol Trading API","version":"3.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.3","info":{"title":"Pear Protocol Trading API","version":"3.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.3","info":{"title":"Pear Protocol Trading API","version":"3.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.3","info":{"title":"Pear Protocol Trading API","version":"3.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.3","info":{"title":"Pear Protocol Trading API","version":"3.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"]}}}}
```