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

idstringRequired

Unique identifier for the vault wallet

Example: vault_1234567890abcdef

leader_addressstringRequired

Leader/owner address

Example: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6

vaultAddressstringRequired

Generated vault contract address from blockchain

Example: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6

agentAddressstringRequired

Privy agent wallet address

Example: 0x1234567890123456789012345678901234567890

isApprovedbooleanRequired

Whether the vault wallet is approved for trading

Example: false

namestringRequired

Vault wallet name

Example: My Trading Vault

aboutstringRequired

Vault wallet description/about

Example: This is my trading vault for automated strategies

imageUrlstringRequired

Image URL for the vault wallet

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

transactionHashstringRequired

Transaction hash from vault creation

Example: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

createdAtstringRequired

Timestamp when the vault wallet was created

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

messagestringRequired

Success message

Example: Vault created successfully with onchain transaction.

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

No content

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 NextPublic Stats

Last updated 3 months ago