P
Privos

Developer Documentation

Build agent-first DeFi

Complete API, MCP tools, webhooks, and payment protocol for integrating AI agents with Aave V3 on Arbitrum.

API Reference (Swagger)Quick Start

Agent Delegation Keys

Create scoped API keys that let AI agents operate on behalf of users. Keys support three permission levels and are SHA-256 hashed for storage.

1. Create a key (Privy auth required)

POST /agent/keys
Authorization: Bearer <privy_token>

{
  "name": "Trading Bot",
  "scopes": ["trade"],
  "maxDailySpendUsd": 500,
  "allowedAssets": ["USDC", "WETH"],
  "expiresInDays": 7
}

// Response: { apiKey: "prv_agent_a1b2c3..." }
// Save this key - it's shown only once!

2. Use the key in requests

// REST API
curl -H "X-Agent-Key: prv_agent_a1b2c3..." \
  https://api.privos.app/aave/positions

// MCP tool call
{
  "tool": "check_health",
  "arguments": {
    "wallet_address": "0x..."
  }
}

Scope Hierarchy

read

getReserves, getPositions, checkHealth, getYieldOpportunities

trade

All read + supply, withdraw, borrow, repay, rebalance

full-access

All trade + key management, policy management

MCP Server

Model Context Protocol server with 9 tools and 2 resources. Any MCP-compatible AI agent (Claude, GPT, etc.) can read positions, check health, and build transactions.

Available Tools

getReservesread

List all Aave V3 reserves with APYs and liquidity

getPositionsread

Get user's supplied/borrowed positions and health

checkHealthread

Health factor analysis with risk level and recommendations

getYieldOpportunitiesread

Find better yield opportunities for current positions

buildSupplytrade

Build a supply transaction for Aave V3

buildWithdrawtrade

Build a withdraw transaction from Aave V3

buildBorrowtrade

Build a borrow transaction on Aave V3

buildRepaytrade

Build a repay transaction for Aave V3

buildRebalancetrade

Build a rebalance (withdraw + supply) across assets

Resources

privos://reserves

Live Aave V3 reserve data (auto-refreshes)

privos://positions/{wallet}

User position data for a specific wallet

Spending Policies

10 programmable constraint types with “most restrictive wins” merging. Policies apply to both agent keys and user-level rules.

allowed_operations

Whitelist of allowed operations (supply, withdraw, borrow, repay, rebalance)

allowed_assets

Whitelist of allowed asset symbols (e.g., USDC, WETH)

max_transaction_usd

Maximum USD value per single transaction

max_daily_spend_usd

Maximum cumulative USD spend per 24h period

max_daily_transactions

Maximum number of transactions per 24h period

min_health_factor

Minimum health factor floor (blocks risky borrows)

max_ltv_percent

Maximum loan-to-value ceiling

time_window_start/end

Restrict operations to specific hours (supports overnight windows)

time_window_timezone

IANA timezone for time window evaluation

auto_rebalance_min_improvement

Minimum APY improvement required for auto-rebalance

Dry-Run Evaluation

POST /agent/policies/evaluate
{
  "operation": "borrow",
  "asset": "USDC",
  "amountUsd": 2000,
  "projectedHealthFactor": 1.8
}

// Response:
{
  "allowed": true,
  "warnings": ["Health factor approaching minimum threshold"],
  "evaluatedPolicies": ["Conservative Policy", "agent-key:uuid"]
}

Webhooks

Ingest external events via HMAC-SHA256 signed webhooks. Price alerts trigger notifications, on-chain events confirm transactions, and agent actions are policy-gated.

POST
/webhooks/price-alert

External price alerts (e.g., from Chainlink). Triggers user notifications for >5% moves.

HMAC-SHA256 signature required
POST
/webhooks/on-chain-event

On-chain events (tx confirmations, liquidation warnings, position changes).

HMAC-SHA256 signature required
POST
/webhooks/agent-action

Agent action requests routed through policy engine before execution.

HMAC-SHA256 signature required

HMAC Signature Verification

// Required headers:
X-Webhook-Signature: sha256=<hmac_hex>
X-Webhook-Timestamp: <unix_seconds>

// Compute HMAC:
const payload = timestamp + "." + JSON.stringify(body);
const signature = hmac("sha256", WEBHOOK_SECRET, payload);

// Replay protection: timestamp must be within 5 minutes

x402 Payments

HTTP 402 Payment Required protocol for machine-to-machine commerce. Agents pay USDC micro-payments on Arbitrum for premium analytics.

Paid Endpoints

/agent/x402/analyze-position$0.01

Deep position analysis with risk assessment

/agent/x402/simulate-strategy$0.005

Strategy simulation with projected outcomes

/agent/x402/optimize-yield$0.02

Yield optimization report with recommendations

/agent/x402/generate-strategy$0.05

Custom AI-generated strategy for your positions

Payment Flow

// 1. Get pricing
GET /agent/x402/pricing

// 2. Submit USDC payment
POST /agent/x402/pay
{ "endpoint": "/agent/x402/analyze-position", "txHash": "0x..." }

// 3. Use receipt to access paid endpoint
POST /agent/x402/analyze-position
X-Payment-Receipt: <receipt_token>
{ "walletAddress": "0x..." }

// Receipts are single-use (replay-proof)

API Endpoints

Authentication

POST
/auth/callback

Privy auth callback

GET
/auth/me

Current user

POST
/auth/refresh

Refresh token

POST
/auth/logout

Invalidate session

Aave V3

GET
/aave/reserves

All reserves (public)

GET
/aave/positions

User positions + E-mode

POST
/aave/build/supply

Build supply tx

POST
/aave/build/withdraw

Build withdraw tx

POST
/aave/build/borrow

Build borrow tx

POST
/aave/build/repay

Build repay tx

Agent Keys

POST
/agent/keys

Create agent delegation key

Privy auth
GET
/agent/keys

List agent keys

Privy auth
DELETE
/agent/keys/:id

Revoke key

Privy auth
POST
/agent/keys/:id/rotate

Rotate key

Privy auth
GET
/agent/session

Current session info

Agent key or Privy

Spending Policies

POST
/agent/policies

Create policy

Privy auth
GET
/agent/policies

List policies

Privy auth
PUT
/agent/policies/:id

Update policy

Privy auth
DELETE
/agent/policies/:id

Delete policy

Privy auth
POST
/agent/policies/evaluate

Dry-run evaluation

Agent key or Privy

Autonomous Execution

GET
/agent/executions

List execution history

Privy auth
GET
/agent/executions/stats

Monitor stats

Privy auth
GET
/agent/executions/:id

Execution details

Privy auth
POST
/agent/executions/simulate

Dry-run simulation

Privy auth
POST
/agent/executions/pause

Pause auto-execution

Privy auth
POST
/agent/executions/resume

Resume auto-execution

Privy auth

Deposit / Base Chain

GET
/deposit/base/balances/:addr

Base L2 token balances

GET
/deposit/base/supported-tokens

Supported Base tokens

POST
/deposit/base/bridge

Bridge Base <-> Arbitrum via Stargate

Ready to integrate?

Explore the full Swagger documentation, create an agent key, and start building in minutes.

Open API DocsContact Support