Vault Wallet

Get vault wallet

get

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

Authorizations

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

idstringRequired

Unique identifier for the vault wallet

Example: vault_1234567890abcdef

vaultAddressobjectRequired

Vault wallet address

Example: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6

leader_addressstringRequired

Vault wallet address

Example: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6

agentAddressstringRequired

Public address

Example: 0x1234567890123456789012345678901234567890

isApprovedbooleanRequired

Whether the vault wallet is approved for trading

Example: false

createdAtstringRequired

Timestamp when the vault wallet was created

Example: 2024-01-01T00:00:00.000Z

updatedAtstringRequired

Timestamp when the vault wallet was last updated

Example: 2024-01-01T00:00:00.000Z

privyWalletIdstringRequired

Privy wallet ID for creating the signer

Example: privy_wallet_1234567890abcdef

nameobject · nullableOptional

Vault wallet name

Example: My Trading Vault

aboutobject · nullableOptional

Vault wallet description/about

Example: This is my trading vault for automated strategies

imageUrlobject · nullableOptional

Image URL for the vault wallet

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

transactionHashobject · nullableOptional

Transaction hash from vault creation

Example: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

401

Unauthorized - invalid or missing token

404

Vault wallet not found

get

/vault-wallet

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

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

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

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

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

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

idstringRequired

Unique identifier for the vault wallet

Example: vault_1234567890abcdef

vaultAddressobjectRequired

Vault wallet address

Example: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6

leader_addressstringRequired

Vault wallet address

Example: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6

agentAddressstringRequired

Public address

Example: 0x1234567890123456789012345678901234567890

isApprovedbooleanRequired

Whether the vault wallet is approved for trading

Example: false

createdAtstringRequired

Timestamp when the vault wallet was created

Example: 2024-01-01T00:00:00.000Z

updatedAtstringRequired

Timestamp when the vault wallet was last updated

Example: 2024-01-01T00:00:00.000Z

privyWalletIdstringRequired

Privy wallet ID for creating the signer

Example: privy_wallet_1234567890abcdef

nameobject · nullableOptional

Vault wallet name

Example: My Trading Vault

aboutobject · nullableOptional

Vault wallet description/about

Example: This is my trading vault for automated strategies

imageUrlobject · nullableOptional

Image URL for the vault wallet

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

transactionHashobject · nullableOptional

Transaction hash from vault creation

Example: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

401

Unauthorized - invalid or missing token

get

/vault-wallet/all

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

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

idstringRequired

Unique identifier for the vault wallet

Example: vault_1234567890abcdef

leader_addressstringRequired

Owner wallet address

Example: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6

vaultAddressstringRequired

Vault contract address

Example: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6

newAgentWalletAddressstringRequired

New agent wallet address for backend trading

Example: 0x1234567890123456789012345678901234567890

messagestringRequired

Success message

Example: Agent wallet refreshed successfully for vault.

401

Unauthorized - invalid or missing token

404

Vault wallet not found or vault not registered

post

/vault-wallet/refreshAPIforVault

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

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

successbooleanRequired

Transfer success status

Example: true

amountstringRequired

Amount transferred

Example: 100.0

assetstringRequired

Asset transferred

Example: USDC

directionstringRequired

Transfer direction

Example: SPOT_TO_PERP

messagestringRequired

Success message

Example: Transfer completed successfully

400

Invalid transfer amount or insufficient balance

401

Unauthorized - invalid or missing token

post

/vault-wallet/spot-to-perp

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

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

successbooleanRequired

Transfer success status

Example: true

amountstringRequired

Amount transferred

Example: 100.0

assetstringRequired

Asset transferred

Example: USDC

directionstringRequired

Transfer direction

Example: SPOT_TO_PERP

messagestringRequired

Success message

Example: Transfer completed successfully

400

Invalid transfer amount or insufficient balance

401

Unauthorized - invalid or missing token

post

/vault-wallet/perp-to-spot

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

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

fromAmountstringRequired

Amount of source asset swapped

Example: 0.1

toAmountstringRequired

Amount of target asset received

Example: 400.0

exchangeRatenumberRequired

Exchange rate used

Example: 4000

fromAssetstringRequired

Source asset

Example: ETH

toAssetstringRequired

Target asset

Example: USDC

messagestringRequired

Success message

Example: Swap and transfer completed successfully

400

Invalid swap parameters or insufficient balance

401

Unauthorized - invalid or missing token

post

/vault-wallet/swap-and-transfer

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Balances retrieved successfully

application/json

spotBalancesobjectRequired

Spot account balances

Example: {"USDC":"100.0","ETH":"0.1","SOL":"2.5"}

perpBalancesobjectRequired

Perp account balances

Example: {"USDC":"50.0","BTC":"0.01"}

totalValuestringRequired

Total account value in USD

Example: 150.0

401

Unauthorized - invalid or missing token

get

/vault-wallet/balances

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"
}

PreviousMarkets NextTrading Fees

Last updated 1 month ago

hashtagGet vault wallet

hashtagCreate a new vault wallet with onchain deployment

hashtagDelete vault wallet

hashtagGet all vault wallets

hashtagRefresh agent wallet for vault

hashtagTransfer USDC from spot to perp account

hashtagTransfer USDC from perp to spot account

hashtagSwap spot token to USDC and transfer to perp

hashtagGet spot and perp account balances

Get vault wallet

Create a new vault wallet with onchain deployment

Delete vault wallet

Get all vault wallets

Refresh agent wallet for vault

Transfer USDC from spot to perp account

Transfer USDC from perp to spot account

Swap spot token to USDC and transfer to perp

Get spot and perp account balances