Vault Wallet

Get vault wallet

get

Retrieve a specific vault wallet by address (agent_address or vault_address)

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

vaultAddressstringRequired

Vault address - can be agent_address (Privy wallet) or vault_address (contract)

Example: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6

Responses

200

Vault wallet retrieved successfully

application/json

401

Unauthorized - invalid or missing token

404

Vault wallet not found

get

/vault-wallet

HTTPcURLJavaScriptPython

GET /vault-wallet?vaultAddress=0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6 HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "vault_1234567890abcdef",
  "vaultAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "leader_address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "agentAddress": "0x1234567890123456789012345678901234567890",
  "isApproved": false,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z",
  "privyWalletId": "privy_wallet_1234567890abcdef",
  "name": "My Trading Vault",
  "about": "This is my trading vault for automated strategies",
  "imageUrl": "https://example.com/images/vault-avatar.png",
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}

Create a new vault wallet with onchain deployment

post

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

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

leader_addressstringRequired

Leader/owner address of the vault

Example: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6

namestringRequired

Name for the vault wallet

Example: My Trading Vault

aboutstringOptional

Description/about text for the vault wallet

Example: This is my trading vault for automated strategies

imageUrlstringRequired

Image URL for the vault wallet

Example: https://example.com/images/vault-avatar.png

configIdnumberRequired

Configuration ID for the vault from frontend (0-based index)

Example: 0

Responses

201

Vault created successfully with onchain transaction

application/json

400

Invalid request parameters

401

Unauthorized - invalid or missing token

500

Failed to create vault (Privy wallet creation or blockchain transaction failed)

post

/vault-wallet

HTTPcURLJavaScriptPython

POST /vault-wallet HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 219

{
  "leader_address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "name": "My Trading Vault",
  "about": "This is my trading vault for automated strategies",
  "imageUrl": "https://example.com/images/vault-avatar.png",
  "configId": 0
}

{
  "id": "vault_1234567890abcdef",
  "leader_address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "vaultAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "agentAddress": "0x1234567890123456789012345678901234567890",
  "isApproved": false,
  "name": "My Trading Vault",
  "about": "This is my trading vault for automated strategies",
  "imageUrl": "https://example.com/images/vault-avatar.png",
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "message": "Vault created successfully with onchain transaction."
}

Delete vault wallet

delete

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

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

vaultAddressstringRequired

Vault address - can be agent_address (Privy wallet) or vault_address (contract)

Example: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6

Responses

204

Vault wallet deleted successfully

401

Unauthorized - invalid or missing token

404

Vault wallet not found

delete

/vault-wallet

HTTPcURLJavaScriptPython

DELETE /vault-wallet?vaultAddress=0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6 HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get all vault wallets

get

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

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

namestringOptional

Filter vault wallets by name (case-insensitive partial match)

Example: My Trading Vault

addressstringOptional

Filter vault wallets by address (matches agent_address or vault_address, case-insensitive partial match)

Example: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6

Responses

200

Vault wallets retrieved successfully

application/json

401

Unauthorized - invalid or missing token

get

/vault-wallet/all

HTTPcURLJavaScriptPython

GET /vault-wallet/all HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "vault_1234567890abcdef",
    "vaultAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "leader_address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "agentAddress": "0x1234567890123456789012345678901234567890",
    "isApproved": false,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "privyWalletId": "privy_wallet_1234567890abcdef",
    "name": "My Trading Vault",
    "about": "This is my trading vault for automated strategies",
    "imageUrl": "https://example.com/images/vault-avatar.png",
    "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
  }
]

Refresh agent wallet for vault

post

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

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

vaultAddressstringRequired

Vault address - can be agent_address (Privy wallet) or vault_address (contract)

Example: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6

Responses

200

Agent wallet refreshed successfully

application/json

401

Unauthorized - invalid or missing token

404

Vault wallet not found or vault not registered

post

/vault-wallet/refreshAPIforVault

HTTPcURLJavaScriptPython

POST /vault-wallet/refreshAPIforVault?vaultAddress=0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6 HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "vault_1234567890abcdef",
  "leader_address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "vaultAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "newAgentWalletAddress": "0x1234567890123456789012345678901234567890",
  "message": "Agent wallet refreshed successfully for vault."
}

Transfer USDC from spot to perp account

post

Transfer USDC directly from spot account to perp account for trading

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

amountstring · min: 0.01Required

Amount of USDC to transfer from spot to perp account

Example: 100.0

assetstringOptional

Asset to transfer (default: USDC)

Default: USDCExample: USDC

Responses

200

Transfer completed successfully

application/json

400

Invalid transfer amount or insufficient balance

401

Unauthorized - invalid or missing token

post

/vault-wallet/spot-to-perp

HTTPcURLJavaScriptPython

POST /vault-wallet/spot-to-perp HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 33

{
  "amount": "100.0",
  "asset": "USDC"
}

{
  "success": true,
  "amount": "100.0",
  "asset": "USDC",
  "direction": "SPOT_TO_PERP",
  "message": "Transfer completed successfully"
}

Transfer USDC from perp to spot account

post

Transfer USDC directly from perp account to spot account

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

amountstring · min: 0.01Required

Amount of USDC to transfer from perp to spot account

Example: 100.0

assetstringOptional

Asset to transfer (default: USDC)

Default: USDCExample: USDC

Responses

200

Transfer completed successfully

application/json

400

Invalid transfer amount or insufficient balance

401

Unauthorized - invalid or missing token

post

/vault-wallet/perp-to-spot

HTTPcURLJavaScriptPython

POST /vault-wallet/perp-to-spot HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 33

{
  "amount": "100.0",
  "asset": "USDC"
}

{
  "success": true,
  "amount": "100.0",
  "asset": "USDC",
  "direction": "SPOT_TO_PERP",
  "message": "Transfer completed successfully"
}

Swap spot token to USDC and transfer to perp

post

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

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

fromAssetstringRequired

Asset to swap from (e.g., ETH, SOL, BTC)

Example: ETH

amountstring · min: 0.001Required

Amount of the source asset to swap

Example: 0.1

toAssetstringOptional

Asset to swap to (default: USDC)

Default: USDCExample: USDC

Responses

200

Swap and transfer completed successfully

application/json

400

Invalid swap parameters or insufficient balance

401

Unauthorized - invalid or missing token

post

/vault-wallet/swap-and-transfer

HTTPcURLJavaScriptPython

POST /vault-wallet/swap-and-transfer HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "fromAsset": "ETH",
  "amount": "0.1",
  "toAsset": "USDC"
}

{
  "fromAmount": "0.1",
  "toAmount": "400.0",
  "exchangeRate": 4000,
  "fromAsset": "ETH",
  "toAsset": "USDC",
  "message": "Swap and transfer completed successfully"
}

Get spot and perp account balances

get

Retrieve balances for both spot and perp accounts

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Balances retrieved successfully

application/json

401

Unauthorized - invalid or missing token

get

/vault-wallet/balances

HTTPcURLJavaScriptPython

GET /vault-wallet/balances HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "spotBalances": {
    "USDC": "100.0",
    "ETH": "0.1",
    "SOL": "2.5"
  },
  "perpBalances": {
    "USDC": "50.0",
    "BTC": "0.01"
  },
  "totalValue": "150.0"
}