# Agent Credit Protocol

> USDC.e credit lines for AI agents on Tempo. Borrow from the vault, use any MPP service, settle later with interest.

## What this is

An ERC4626 lending vault on Tempo (chain 4217). LPs deposit USDC.e. Operators register with a credit card + wallet signature. The vault lends USDC.e to agents. Agents use the funds to call any MPP-enabled API (OpenRouter, Exa, Browserbase, etc.) via Tempo sessions or charges. Operators settle debt (principal + interest) — interest flows to LPs as yield.

## Quick start for agents

### Step 1: Register as an operator

You need a wallet address and a credit card (Stripe test mode: use `4242 4242 4242 4242`).

**Important:** Register with your **tempo CLI wallet address** (run `tempo wallet -t whoami` to get it). This is where borrowed funds will be sent, and where `tempo request` pays from.

```bash
# 1. Get a signature nonce
curl -X POST $BASE_URL/api/auth/nonce \
  -H 'Content-Type: application/json' \
  -d '{"walletAddress": "0xYOUR_WALLET"}'
# Returns: { nonce, message }

# 2. Sign the message with your wallet (EIP-191 personal sign)

# 3. Create Stripe setup intent
curl -X POST $BASE_URL/api/register \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@example.com", "walletAddress": "0xYOUR_WALLET"}'
# Returns: { clientSecret, customerId }

# 4. Save card via Stripe.js using clientSecret, then confirm:
curl -X POST $BASE_URL/api/register/confirm \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": "cus_...",
    "walletAddress": "0xYOUR_WALLET",
    "email": "you@example.com",
    "signature": "0xSIGNED_MESSAGE"
  }'
# Returns: { approved: true, tx: "0x..." }
```

**Or use the simplified agent endpoint (one call after nonce + signature):**

```bash
curl -X POST $BASE_URL/api/register/agent \
  -H 'Content-Type: application/json' \
  -d '{
    "walletAddress": "0xYOUR_WALLET",
    "email": "agent@example.com",
    "signature": "0xSIGNED_NONCE_MESSAGE",
    "stripeToken": "tok_visa"
  }'
# Returns: { approved: true, tx: "0x..." }
# tok_visa is Stripe's test token — works without a browser card form.
```

### Step 2: Call paid services through the proxy

The vault pays services directly on your behalf — no need to hold funds. Just send requests through `/api/proxy`. The vault handles the 402 payment challenge, pays the service on-chain, and accrues debt on your operator account.

```bash
# Weather geocode ($0.005)
curl -X POST $BASE_URL/api/proxy \
  -H 'Content-Type: application/json' \
  -d '{
    "agentAddress": "0xYOUR_WALLET",
    "targetUrl": "https://weather.mpp.paywithlocus.com/openweather/geocode",
    "method": "POST",
    "headers": {"Content-Type": "application/json"},
    "body": "{\"q\": \"Tokyo\"}"
  }'

# Exa web search ($0.005)
curl -X POST $BASE_URL/api/proxy \
  -H 'Content-Type: application/json' \
  -d '{
    "agentAddress": "0xYOUR_WALLET",
    "targetUrl": "https://exa.mpp.tempo.xyz/search",
    "method": "POST",
    "headers": {"Content-Type": "application/json"},
    "body": "{\"query\": \"AI agents\", \"numResults\": 3, \"type\": \"neural\"}"
  }'

# Browserbase search ($0.01)
curl -X POST $BASE_URL/api/proxy \
  -H 'Content-Type: application/json' \
  -d '{
    "agentAddress": "0xYOUR_WALLET",
    "targetUrl": "https://mpp.browserbase.com/search",
    "method": "POST",
    "headers": {"Content-Type": "application/json"},
    "body": "{\"query\": \"autonomous AI agents\"}"
  }'
```

The proxy returns `{ status, body, headers }`. The `body` contains the service response.
Debt accrues per-second with interest (5-50% APY based on vault utilization). Credit limit: $0.50 per operator.

**Note:** Session-based services (OpenRouter, Anthropic, OpenAI) are not yet supported through the proxy. Coming soon — pending ERC-1271 escrow support on Tempo. Charge-based services (Weather, Exa, Browserbase, fal.ai, StableStudio, etc.) work now.

### Step 4: Check and settle debt

```bash
# Check what you owe
curl $BASE_URL/api/operator/0xYOUR_WALLET/debt
# Returns: { principal, interest, total }

# Settle from the dashboard — connect wallet, click "Pay Debt"
# Or settle on-chain directly:
#   1. USDC.e.approve(vaultAddress, totalOwed)
#   2. vault.settleDebt(operatorAddress)
```

## API reference

### Public (no auth)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/` | Dashboard UI |
| GET | `/api/config` | Vault address, chain info |
| GET | `/api/vault` | Vault state: TVL, utilization, rates |
| POST | `/api/auth/nonce` | Get signature nonce for wallet verification |
| POST | `/api/register` | Create Stripe setup intent |
| POST | `/api/register/confirm` | Confirm registration (card + wallet sig) |
| GET | `/api/operator/:address` | Check operator approval status |
| GET | `/api/operator/:address/debt` | Debt breakdown (principal + interest) |
| GET | `/api/billing` | All agents billing snapshot |
| GET | `/api/payments` | Payment event log |
| GET | `/api/payments/stats` | Payment statistics |
| POST | `/api/proxy` | Call a service through the vault `{agentAddress, targetUrl, method, headers, body}` |
| POST | `/api/register/agent` | One-call agent registration `{walletAddress, email, signature, stripeToken}` |
| GET | `/api/auth/nonce?wallet=0x...` | Get nonce (also supports POST) |

## Contract

- **Vault**: `0xf70c47b76b62cec7e3b6f0f3e8d863756424d17c` on Tempo mainnet (4217)
- **Token**: USDC.e `0x20c000000000000000000000b9537d11c60e8b50`
- **Model**: ERC4626 — deposit/withdraw for LPs, payCharge/settle for credit

### Key functions

```solidity
// LP operations (ERC4626)
function deposit(uint256 assets, address receiver) returns (uint256 shares)
function withdraw(uint256 assets, address receiver, address owner) returns (uint256 shares)

// Credit operations (admin only)
function payCharge(address agent, address recipient, uint128 amount) // vault pays service
function lend(address agent, uint256 amount)           // send USDC.e to agent (future: sessions)
function registerAgent(address agent, address operator) // link agent to operator
function approveOperator(address operator)              // approve an operator
function setCreditLimit(address operator, uint256 limit)

// Settlement (anyone can pay on behalf of operator)
function settleDebt(address operator)

// View
function operatorOwes(address) returns (principal, interest, total)
function agentBorrowed(address) returns (uint256)
function totalLent() returns (uint256)
function currentRateBps() returns (uint256)
function utilizationBps() returns (uint256)
```

## Interest rate model

Aave-style curve based on vault utilization:
- 0% utilization → 5% APY (cheap credit)
- 80% utilization → 15% APY (optimal)
- 100% utilization → 50% APY (incentivizes repayment)

Interest accrues per-second on-chain. Settlement pays principal + accrued interest. Interest raises the vault's share price, distributing yield to all LPs.