API Endpoints Reference

Complete reference for SnowMind REST API endpoints. All requests require Privy authentication.

Portfolio Endpoints

Get Portfolio State

GET /portfolio/{address}

Fetch real-time balances, APY, and allocations for a smart account.

Parameters

address (path, required) — Smart account address (0x-prefixed)

Deposit Endpoints

Deposit with Protocol Selection

POST /accounts/{address}/deposit

Record a USDC deposit, select protocols, and optionally trigger rebalance.

Request Body

{
  "allowedProtocols": ["aave", "benqi", "spark"],
  "fundingTxHash": "0xabcd1234...",
  "fundingAmountUsdc": "1000.50",
  "fundingSource": "dashboard_wallet_transfer",
  "allocationCaps": {
    "aave": 50,
    "benqi": 30,
    "spark": 20
  },
  "triggerRebalance": true
}

Response

{
  "allowedProtocols": ["aave", "benqi", "spark"],
  "allocationCaps": {
    "aave": 50,
    "benqi": 30,
    "spark": 20
  },
  "effectiveCapTotalPct": 100,
  "idleRemainderPossible": false,
  "updatedRows": 1,
  "fundingTxHash": "0xabcd1234...",
  "fundingAmountUsdc": "1000.50",
  "fundingRecorded": true,
  "rebalanceQueued": true
}

Withdrawal Endpoints

Preview Withdrawal

POST /withdrawals/preview

Calculate fees and withdrawable amount without executing.

Request Body

{
  "smartAccountAddress": "0x...",
  "withdrawAmount": "500.00",
  "isFullWithdrawal": false
}

Execute Withdrawal

POST /withdrawals/execute

Execute a full or partial withdrawal with a signed authorization.

Request Body

{
  "smartAccountAddress": "0x...",
  "withdrawAmount": "500.00",
  "isFullWithdrawal": false,
  "ownerSignature": "0x...",
  "signatureMessage": "SnowMind Withdrawal Authorization...",
  "signatureTimestamp": 1714540000
}

Signature Required

Every withdrawal must include a fresh user signature from the owner wallet. Agents cannot withdraw without user authorization.

Protocol Management

Update Allowed Protocols

PUT /accounts/{address}/allowed-protocols

Change the set of protocols SnowMind can deploy into.

Request Body

{
  "allowedProtocols": ["aave", "benqi"]
}

Update Allocation Caps

PUT /accounts/{address}/allocation-caps

Adjust per-protocol max allocation percentages.

Request Body

{
  "allocationCaps": {
    "aave": 60,
    "benqi": 40
  }
}

Session Key Endpoints

Session keys grant SnowMind scoped execution permissions. These are required for automated deposits and withdrawals.

Store Session Key

POST /accounts/{address}/session-key

Revoke Session Key

POST /accounts/{address}/session-key/revoke

Authentication Header

Authorization: Bearer {YOUR_PRIVY_TOKEN}

Error Responses

400 Bad Request — Invalid parameters
401 Unauthorized — Missing or invalid auth token
404 Not Found — Account not found
409 Conflict — State conflict (funded protocol exclusion)
429 Too Many Requests — Rate limit exceeded
500 Internal Server Error — Retry later