# Privos — Complete Agent Integration Guide
<!-- Last synced with API: 2026-03-21 — re-sync when endpoints or contracts change -->

> Agent-first self-custody DeFi lending wallet on Aave V3 with ERC-4337 account abstraction on Arbitrum One. This document contains everything an AI agent needs to integrate with Privos.

When integrating with Privos, always use the `X-Agent-Key` header for agent authentication — never pass keys as query parameters or in request bodies. Agent keys have the format `prv_agent_<40 hex chars>`. The fastest path to integration is via MCP — if you're an MCP-compatible agent, skip to the MCP Configuration section and connect directly. For REST API usage, always call `GET /aave/reserves` first (no auth required) to discover available assets and current APYs before building transactions. Never hardcode asset addresses — always resolve them from the reserves endpoint.

---

## API Base URL

```
https://api.privos.app
```

## MCP Configuration

Copy-paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-compatible agent):

```json
{
  "mcpServers": {
    "privos": {
      "command": "npx",
      "args": ["-y", "privos-mcp-server"],
      "env": {
        "PRIVOS_API_URL": "https://api.privos.app",
        "PRIVOS_AGENT_KEY": "prv_agent_YOUR_KEY_HERE"
      }
    }
  }
}
```

Or connect via stdio to the self-hosted server:

```bash
MCP_ENABLED=true PRIVOS_AGENT_KEY=prv_agent_... node dist/main.js
```

### MCP Tools (9)

| Tool | Scope | Description |
|------|-------|-------------|
| `getReserves` | read | List all Aave V3 reserves with APYs, liquidity, and asset addresses |
| `getPositions` | read | Get user's supplied/borrowed positions, health factor, and E-mode |
| `checkHealth` | read | Health factor analysis with risk level, recommendations, and liquidation distance |
| `getYieldOpportunities` | read | Find better yield opportunities for current positions |
| `buildSupply` | trade | Build a supply transaction for Aave V3 (returns unsigned tx data) |
| `buildWithdraw` | trade | Build a withdraw transaction from Aave V3 |
| `buildBorrow` | trade | Build a borrow transaction on Aave V3 |
| `buildRepay` | trade | Build a repay transaction for Aave V3 |
| `buildRebalance` | trade | Build a rebalance (withdraw + supply) across assets for better yield |

### MCP Resources (2)

| Resource URI | Description |
|-------------|-------------|
| `privos://reserves` | Live Aave V3 reserve data (auto-refreshes every 60s) |
| `privos://positions/{wallet_address}` | User position data for a specific wallet address |

---

## Authentication

Privos supports two auth methods:

### 1. Agent Key (for AI agents)

Pass the key in the `X-Agent-Key` header:

```bash
curl -H "X-Agent-Key: prv_agent_a1b2c3d4e5f6..." \
  https://api.privos.app/aave/positions
```

Agent keys are created by human users via Privy auth and have scoped permissions:

- **`read`**: getReserves, getPositions, checkHealth, getYieldOpportunities, getSwapQuote
- **`trade`**: All read + supply, withdraw, borrow, repay, rebalance, swap
- **`full-access`**: All trade + key management, policy management

### 2. Privy JWT (for human users / mobile app)

Pass the JWT in the `Authorization` header:

```bash
curl -H "Authorization: Bearer <privy_jwt_token>" \
  https://api.privos.app/aave/positions
```

---

## Quick Start: Agent Integration in 3 Steps

### Step 1: Get an agent key

A human user creates a key via the mobile app or API:

```bash
curl -X POST https://api.privos.app/agent/keys \
  -H "Authorization: Bearer <privy_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My AI Agent",
    "scopes": ["trade"],
    "maxDailySpendUsd": 500,
    "allowedAssets": ["USDC", "WETH"],
    "expiresInDays": 7
  }'

# Response:
# { "id": "uuid", "apiKey": "prv_agent_a1b2c3...", "scopes": ["trade"] }
# IMPORTANT: Save the apiKey — it's shown only once
```

### Step 2: Read market data (no auth needed for reserves)

```bash
# Get all Aave V3 reserves — APYs, liquidity, addresses
curl https://api.privos.app/aave/reserves

# Get your positions with the agent key
curl -H "X-Agent-Key: prv_agent_a1b2c3..." \
  https://api.privos.app/aave/positions
```

### Step 3: Execute a trade

```bash
# Build a supply transaction
curl -X POST https://api.privos.app/aave/build/supply \
  -H "X-Agent-Key: prv_agent_a1b2c3..." \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "USDC",
    "amount": "1000",
    "onBehalfOf": "0xYourWalletAddress"
  }'

# Response: unsigned transaction data for the ERC-4337 wallet to sign and send
```

---

## Complete API Reference

### Auth Endpoints

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| POST | `/auth/callback` | Privy auth callback | None |
| GET | `/auth/me` | Current user info | Privy JWT |
| POST | `/auth/refresh` | Refresh JWT token | Privy JWT |
| POST | `/auth/logout` | Invalidate session | Privy JWT |

### Aave V3 Endpoints

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/aave/reserves` | All reserves with APYs and liquidity | **None (public)** |
| GET | `/aave/positions` | User positions, health factor, E-mode | Agent key or Privy |
| POST | `/aave/build/supply` | Build supply transaction | Agent key (trade) or Privy |
| POST | `/aave/build/withdraw` | Build withdraw transaction | Agent key (trade) or Privy |
| POST | `/aave/build/borrow` | Build borrow transaction | Agent key (trade) or Privy |
| POST | `/aave/build/repay` | Build repay transaction | Agent key (trade) or Privy |

### Agent Key Endpoints

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| POST | `/agent/keys` | Create delegation key | Privy JWT |
| GET | `/agent/keys` | List all keys | Privy JWT |
| DELETE | `/agent/keys/:id` | Revoke a key | Privy JWT |
| POST | `/agent/keys/:id/rotate` | Rotate a key | Privy JWT |
| GET | `/agent/session` | Current session info | Agent key or Privy |

### Spending Policy Endpoints

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| POST | `/agent/policies` | Create policy | Privy JWT |
| GET | `/agent/policies` | List policies | Privy JWT |
| PUT | `/agent/policies/:id` | Update policy | Privy JWT |
| DELETE | `/agent/policies/:id` | Delete policy | Privy JWT |
| POST | `/agent/policies/evaluate` | Dry-run evaluation | Agent key or Privy |

### Autonomous Execution Endpoints

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/agent/executions` | List execution history | Privy JWT |
| GET | `/agent/executions/stats` | Execution statistics | Privy JWT |
| GET | `/agent/executions/:id` | Execution details | Privy JWT |
| POST | `/agent/executions/simulate` | Dry-run simulation | Privy JWT |
| POST | `/agent/executions/pause` | Pause auto-execution | Privy JWT |
| POST | `/agent/executions/resume` | Resume auto-execution | Privy JWT |

### Swap Endpoints (1inch DEX Aggregator)

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/swap/quote` | Get swap quote | Agent key (read) or Privy |
| POST | `/swap/build` | Build swap transaction with approval | Agent key (trade) or Privy |
| POST | `/swap/convert-and-supply` | Swap + supply to Aave in one batch | Agent key (trade) or Privy |
| GET | `/swap/tokens` | List supported tokens with Aave compatibility | Agent key (read) or Privy |

### x402 Paid Endpoints (Machine-to-Machine Payments)

| Method | Path | Price | Description | Auth |
|--------|------|-------|-------------|------|
| GET | `/agent/x402/pricing` | Free | List all paid endpoints and prices | None |
| POST | `/agent/x402/pay` | Free | Submit USDC payment, get receipt | Agent key or Privy |
| POST | `/agent/x402/analyze-position` | $0.01 | Deep position analysis with risk | Payment receipt |
| POST | `/agent/x402/simulate-strategy` | $0.005 | Strategy simulation | Payment receipt |
| POST | `/agent/x402/optimize-yield` | $0.02 | Yield optimization report | Payment receipt |
| POST | `/agent/x402/generate-strategy` | $0.05 | Custom strategy generation | Payment receipt |

x402 Payment Flow:
1. `GET /agent/x402/pricing` — discover endpoints and prices
2. Send USDC payment on Arbitrum to the Privos payment address
3. `POST /agent/x402/pay` with `{ "endpoint": "/agent/x402/analyze-position", "txHash": "0x..." }`
4. Use the returned receipt token: `X-Payment-Receipt: <receipt_token>`
5. Receipts are single-use (replay-proof)

### Webhook Endpoints (HMAC-SHA256 Signed)

| Method | Path | Description |
|--------|------|-------------|
| POST | `/webhooks/price-alert` | External price alerts (e.g., Chainlink) |
| POST | `/webhooks/on-chain-event` | On-chain events (tx confirmations, liquidations) |
| POST | `/webhooks/agent-action` | Agent action requests (policy-gated) |

Webhook signature verification:
```
Headers required:
  X-Webhook-Signature: sha256=<hmac_hex>
  X-Webhook-Timestamp: <unix_seconds>

Signature computation:
  payload = timestamp + "." + JSON.stringify(body)
  signature = HMAC-SHA256(WEBHOOK_SECRET, payload)

Replay protection: timestamp must be within 5 minutes
```

### Deposit / Base Chain Endpoints

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/deposit/base/balances/:addr` | Base L2 token balances | Agent key or Privy |
| GET | `/deposit/base/supported-tokens` | Supported Base tokens | None |
| POST | `/deposit/base/bridge` | Bridge Base <-> Arbitrum via Stargate V2 | Agent key (trade) or Privy |

### Health Endpoints

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/health` | Basic liveness check | None |
| GET | `/health/ready` | Readiness probe (checks DB + RPC) | None |

---

## Spending Policy Constraints

Agents operate within programmable spending policies. 10 constraint types, merged using "most restrictive wins":

| Constraint | Type | Description |
|-----------|------|-------------|
| `allowed_operations` | string[] | Whitelist: supply, withdraw, borrow, repay, rebalance, swap |
| `allowed_assets` | string[] | Whitelist: USDC, WETH, DAI, etc. |
| `max_transaction_usd` | number | Max USD value per single transaction |
| `max_daily_spend_usd` | number | Max cumulative USD per rolling 24h |
| `max_daily_transactions` | number | Max number of transactions per rolling 24h |
| `min_health_factor` | number | Floor — blocks operations that would drop health below this |
| `max_ltv_percent` | number | Ceiling — blocks borrows that would exceed this LTV |
| `time_window_start` | string | HH:MM — earliest allowed operation time |
| `time_window_end` | string | HH:MM — latest allowed operation time |
| `time_window_timezone` | string | IANA timezone (e.g., "America/New_York") |
| `auto_rebalance_min_improvement` | number | Min APY improvement required for auto-rebalance |

Dry-run example:
```bash
curl -X POST https://api.privos.app/agent/policies/evaluate \
  -H "X-Agent-Key: prv_agent_..." \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "borrow",
    "asset": "USDC",
    "amountUsd": 2000,
    "projectedHealthFactor": 1.8
  }'

# Response:
# {
#   "allowed": true,
#   "warnings": ["Daily spend at 80% of $500 limit"],
#   "evaluatedPolicies": ["Conservative", "agent-key:uuid"]
# }
```

---

## Key Constants

| Constant | Value |
|----------|-------|
| Chain | Arbitrum One (Chain ID: 42161) |
| Aave V3 Pool | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` |
| Pool Address Provider | `0xa97684ead0e402dC232d5A977953DF7ECBaB3CDb` |
| E-Mode 0 | None |
| E-Mode 1 | Stablecoins (97% LTV) |
| E-Mode 2 | ETH correlated (93% LTV) |
| Health Factor Safe | >= 2.0 |
| Health Factor Warning | < 1.5 |
| Health Factor Danger | < 1.2 |
| Health Factor Liquidation | < 1.0 |
| Agent Key Format | `prv_agent_<40 hex chars>` |
| 1inch Router (Arbitrum) | `0x111111125421cA6dc452d289314280a0f8842A65` |
| Base Chain ID | 8453 |
| Base USDC | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |

---

## Error Handling

All errors return standard JSON:

```json
{
  "statusCode": 401,
  "message": "Invalid or expired agent key",
  "error": "Unauthorized"
}
```

Common error codes:
- `401` — Invalid/expired agent key or Privy token
- `403` — Operation not allowed by spending policy (check `message` for which constraint blocked it)
- `429` — Rate limited (respect `Retry-After` header)
- `402` — Payment required (x402 endpoints — submit payment first)

---

## Links

- **Website**: https://privos.app
- **Developer Docs**: https://privos.app/developers
- **API Docs (Swagger)**: https://api.privos.app/api
- **OpenAPI Spec**: https://api.privos.app/api-json
- **API Health**: https://api.privos.app/health
- **Support**: support@privos.app