# ClawVault Agent Skill

You have access to ClawVault, a security middleware for AI agents. ClawVault protects FOUR spending channels:
1. **Crypto payments** — USDC transfers on Base, Ethereum, Arbitrum, Polygon, BNB Smart Chain, Avalanche, and Solana
2. **Token swaps** — Swap any supported token on Solana via dFlow (SOL, USDC, USDT, BONK, JUP, WIF, PYTH, RAY, ORCA, or any mint address)
3. **Prediction markets** — Buy/sell/redeem Kalshi prediction market outcomes on Solana via dFlow
4. **Agent Card** — Virtual Visa card for any merchant worldwide (SaaS, APIs, cloud, etc.)

All channels use the same rules engine. Every transaction is validated against user-defined rules. Transactions within rules auto-approve; transactions outside rules require human approval via Telegram or dashboard.

## Important: Two Solana Wallets

ClawVault uses **two separate Solana wallets** for different purposes:

1. **Main Vault** (Crossmint smart wallet) — Used for crypto payments and token swaps. This is your primary vault shown on the dashboard.
2. **Prediction Wallet** (standalone Solana keypair) — Used exclusively for prediction market trades. Required because dFlow Proof KYC verification needs direct wallet signing that smart wallets cannot do.

Swaps draw from and deposit to your **main vault**. Prediction market trades draw from and deposit to your **prediction wallet**. Fund your prediction wallet with USDC via the ClawVault dashboard.

**Before making ANY prediction trade**, always call `GET /v1/prediction/wallet` first to check readiness:
- If `exists: false`: Tell the user "You need to set up a prediction wallet first — go to your ClawVault dashboard (Predictions page)."
- If `exists: true` but `kycVerified: false`: Tell the user "Your prediction wallet needs KYC verification — complete it in your ClawVault dashboard (Predictions page) or at dFlow Proof."
- If `exists: true` and `kycVerified: true`: Good to trade. Check `balance.usdc` — if insufficient, tell the user to fund their prediction wallet via the ClawVault dashboard.
Do NOT attempt a prediction buy/sell without checking wallet status first.

## API Base URL
```
https://api.clawvault.cc
```

## Authentication
All requests require your API key in the Authorization header:
```
Authorization: Bearer cv_live_xxxxx
```

---

# CRYPTO PAYMENTS (On-Chain)

## 1. Request a Crypto Payment

When you need to send tokens to a blockchain address:

```http
POST /v1/payments
Content-Type: application/json

{
  "amount": "50.00",
  "token": "USDC",
  "recipient": "0x1234567890abcdef1234567890abcdef12345678",
  "chain": "base",
  "reason": "Payment for services rendered"
}
```

Supported chains: `base`, `ethereum`, `arbitrum`, `polygon`, `bnb`, `avalanche`, `solana`
Supported tokens: `USDC` (all chains), `SOL` (Solana only), or any SPL token mint address (Solana only)

**SOL transfer example:**
```json
{ "amount": "0.5", "token": "SOL", "recipient": "FsdxRx...", "chain": "solana", "reason": "Send SOL" }
```

### Possible Statuses
- `auto_approved` — Payment executed immediately (within rules)
- `pending` — Awaiting human approval via Telegram/dashboard
- `manually_approved` — Approved by user via Telegram/dashboard
- `blocked_by_rule` — Blocked by rules engine (not sent for approval)
- `denied` — Payment was rejected by user
- `expired` — Approval window closed
- `executed` — On-chain execution completed
- `failed` / `execution_failed` — On-chain execution failed

---

## 2. Check Before Sending (Dry Run)

```http
POST /v1/rules/check
Content-Type: application/json

{
  "amount": "50.00",
  "token": "USDC",
  "recipient": "0x1234...",
  "chain": "base"
}
```

If `autoApprove: false`, tell the user the payment needs their approval.

---

## 3. Get Vaults

```http
GET /v1/vaults
```

Returns all vaults with balance, chain, and agent count. Solana vaults include `allTokens` — a list of ALL token balances (not just USDC/SOL) so you can see tokens acquired via swaps.

---

# TOKEN SWAPS (Solana via dFlow)

Swap any supported token on Solana. Powered by dFlow's JIT Router for best execution.

## 4. Get Swap Quote (No Execution)

```http
POST /v1/swap/quote
Content-Type: application/json

{
  "fromToken": "USDC",
  "toToken": "SOL",
  "amount": "10"
}
```

Returns: inputAmount, outputAmount (human-readable), outputAmountRaw (smallest denomination), priceImpact, slippageBps (basis points), route.

## 5. Execute Swap

```http
POST /v1/swap
Content-Type: application/json

{
  "fromToken": "USDC",
  "toToken": "SOL",
  "amount": "10",
  "slippage": 0.5,
  "reason": "Swap for gas fees"
}
```

**slippage** is in **percentage** (0.5 = 0.5%, 1 = 1%, 3 = 3%). NOT basis points. Default: uses the quote's recommended slippage if omitted.

### Supported Tokens
SOL, USDC, USDT, JUP, BONK, WIF, PYTH, RAY, ORCA — or any token by Solana mint address.

### Swap Rules (enforced automatically)
- Max per swap, daily/weekly swap budget
- Minimum swap amount, max slippage % (rule value is also in percentage)
- Cooldown between swaps, max swaps per day
- Allowed token list, require reason toggle

---

# PREDICTION MARKETS (Kalshi via dFlow)

Trade on Kalshi prediction markets on Solana. Categories include crypto, politics, sports, economics, science, entertainment.

## 6. List Prediction Markets

```http
GET /v1/prediction/markets?limit=10&status=active&category=crypto&search=trump&sort=volume24h
```

All query params are optional. Defaults to `status=active` and sorted by `volume24h` descending.

| Param | Description |
|-------|-------------|
| `status` | Filter: `active` (default), `closed`, `settled`, `determined`, `finalized`. Invalid values return empty results with a `note` listing valid options. |
| `category` | Filter by category: `crypto`, `politics`, `sports`, `economics`, `entertainment`, `science`. Use `GET /v1/prediction/categories` for full list. |
| `search` | Full-text search across title, ticker, category |
| `sort` | Sort by: `volume24h` (default), `volume`, `liquidity`, `openInterest` |
| `limit` | Max results (default 50, max 200) |
| `page` | Page number for pagination (default 1). Response includes `totalPages` and `totalCount`. |
| `eventTicker` | Filter by event ticker (e.g. `KXBTCD-26MAR1017`) to group related markets |
| `minPrice` | Minimum yesPrice in cents (0-100). Use 20 for bets ≥20¢ |
| `maxPrice` | Maximum yesPrice in cents (0-100). Use 80 for bets ≤80¢ |

Returns markets with ticker, title, yesPrice/noPrice (in cents 0-100), volume, volume24h, liquidity, openInterest, and status.

## 7. Get Specific Market

```http
GET /v1/prediction/markets/{ticker}
```

## 8. Buy Prediction Outcome

```http
POST /v1/prediction/buy
Content-Type: application/json

{
  "marketTicker": "KXTRUMPOUT27-27-28",
  "outcome": "yes",
  "amount": "5",
  "reason": "Betting Trump stays in office through 2028"
}
```

Returns: betId, status, txHash, explorerUrl.

## 9. Sell Prediction Position

```http
POST /v1/prediction/sell
Content-Type: application/json

{
  "marketTicker": "KXTRUMPOUT27-27-28",
  "outcome": "yes",
  "amount": "5",
  "reason": "Taking profit"
}
```

## 10. Redeem Settled Prediction

```http
POST /v1/prediction/redeem
Content-Type: application/json

{
  "marketTicker": "KXTRUMPOUT27-27-28",
  "outcome": "yes",
  "amount": "5"
}
```

Only works on markets with status `determined` or `finalized`.

## 11. Get Prediction Positions

```http
GET /v1/prediction/positions
```

Returns on-chain Token-2022 positions with current value and market status.

## 12. Check Prediction Wallet Status

```http
GET /v1/prediction/wallet
```

Returns prediction wallet address, USDC/SOL balance, and KYC verification status.

## 13. Prediction Wallet Info

The prediction wallet is created and funded by the user in the ClawVault dashboard (Predictions page). You do NOT need to create it — just check its status with `GET /v1/prediction/wallet`. If the user doesn't have one yet, tell them to set it up at their ClawVault dashboard. If it has 0 USDC, tell the user to fund it via the dashboard.

### Prediction Rules (enforced automatically)
- Max per bet, daily/weekly prediction budget
- Minimum bet amount, max total exposure
- Max open positions, max bets per day
- Cooldown between bets, require reason toggle
- Allowed categories, allow sell/redeem toggles

## 14. List Prediction Categories

```http
GET /v1/prediction/categories
```

Returns available categories: crypto, economics, entertainment, other, politics, science, sports.

---

# AGENT CARD (Virtual Visa via AgentCard)

Issue disposable virtual Visa cards for real-world purchases. Each card is backed by a Stripe payment method hold — agents cannot overspend.

**Setup (one-time):**
1. `POST /v1/card/setup` — create cardholder, get Stripe checkout URL
2. User completes Stripe checkout to attach payment method
3. `GET /v1/card/setup/status` — verify payment method attached

**Purchase flow:**
1. `POST /v1/card/purchase` — creates virtual Visa, returns PAN/CVV/expiry
2. Agent uses card details to complete purchase
3. `POST /v1/card/close` — close card after use (releases unused hold)

**Limits:** Max $500 per card, max 5 active cards. Subject to card rules (cardsEnabled, cardPerTxLimit, cardDailyLimit, cardWeeklyLimit, cardAllowedMerchants, cardCooldownSeconds).

## Card Setup

```http
POST /v1/card/setup
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1990-01-15"
}
```

Response: `{ status, cardholderId, checkoutUrl, message }`
- `payment_method_required` — redirect user to checkoutUrl
- `ready` — card is ready to use

## Check Setup Status

```http
GET /v1/card/setup/status
```

Response: `{ status, hasCardholder, hasPaymentMethod }`

## Request Card Purchase

```http
POST /v1/card/purchase
Content-Type: application/json

{
  "amount": "25.00",
  "merchant": "OpenAI",
  "reason": "GPT-4 API credits"
}
```

Response (auto-approved):
```json
{
  "transactionId": "ctx_...",
  "status": "issued",
  "card": {
    "pan": "4242424242424242",
    "cvv": "123",
    "expiry": "12/28",
    "last4": "4242",
    "spendLimitUsd": "25.00",
    "balanceUsd": "25.00"
  }
}
```

If rules require approval: returns `status: "pending_approval"` with `transactionId`. Poll `GET /v1/card/transactions/:id` for updates.

## Card Balance (Active Cards)

```http
GET /v1/card/balance
```

Returns list of active (OPEN) cards with current balances.

## Dry-Run Check

```http
POST /v1/card/check
Content-Type: application/json

{
  "amount": "25.00",
  "merchant": "OpenAI"
}
```

Returns `{ allowed, autoApprove, reason }` without creating a card.

## Close Card

```http
POST /v1/card/close
Content-Type: application/json

{ "cardId": "card_abc123" }
```

Closes card and releases uncaptured hold back to payment method.

## Card Transactions

```http
GET /v1/card/transactions
GET /v1/card/transactions/:id
```

Query params: `?status=issued&limit=20&offset=0`
Valid statuses: `pending_approval`, `issued`, `closed`, `denied`

---

# SUBSCRIPTION MANAGEMENT

Manage your ClawVault subscription. Prices are in USD, paid with $VAULT tokens at market rate.

**Payment token:** $VAULT on Solana (`77UrDzChDJmSQbQDEjBGLmaKqyxbWiEEzSTtEWwbpump`)
**Treasury:** `FsdxRx5HJWiSFWoQvYiBmkRY6K35mdthoaay3ZgTr9Yr`
**Burn mechanism:** Every subscription payment splits: 95% to treasury, 5% permanently burned (deflationary)
**Pricing:** USD-denominated, converted to $VAULT at current market rate at time of payment

## Tiers & Pricing

| Tier | Price (USD/month) | Tx/Month | Agents |
|------|-------------------|----------|--------|
| Free | $0 | 50 | 1 |
| Starter | $5 | 100 | 3 |
| Pro | $20 | 1,000 | Unlimited |
| Unlimited | $50 | Unlimited | Unlimited |

Prices are in USD. When you pay, ClawVault converts the USD amount to the equivalent $VAULT at the current market rate via dFlow. For example, if Pro costs $20 and $VAULT trades at $0.001, you pay ~20,000 $VAULT.

## When to Upgrade

You should upgrade when:
- `GET /v1/subscription` returns `status: "near_limit"` (80%+ of tx limit used) or `"at_limit"`
- You need more agent slots than your tier allows
- The user asks you to upgrade or manage their subscription
- You are about to hit the limit and continuing work requires more transactions

## How to Pay: The Complete Flow

Subscriptions are paid with **$VAULT tokens**. The system converts the USD price to $VAULT automatically. If you don't have enough $VAULT, swap USDC to $VAULT first.

### Step 1: Check subscription status
```http
GET /v1/subscription
```
Response includes: `tier`, `transactions.used`/`limit`/`percentage`, `agents.used`/`limit`, `billing`, `vaultToken.balance` (your $VAULT balance), `upgradeOptions[]` (each with `tier`, `priceUsd`, `priceVault`, `canAfford`), and `status` (ok/near_limit/at_limit). The `priceVault` field shows how many $VAULT tokens the tier costs at current market rate. `pricing.vaultPerUsd` shows the conversion rate.

### Step 2: If you need $VAULT tokens, swap USDC → $VAULT
Check `upgradeOptions[].canAfford` for your target tier. If `false`, you need to swap first:
```http
POST /v1/swap
Content-Type: application/json

{
  "fromToken": "USDC",
  "toToken": "77UrDzChDJmSQbQDEjBGLmaKqyxbWiEEzSTtEWwbpump",
  "amount": "20",
  "reason": "Acquiring $VAULT for Pro subscription upgrade ($20 USD)"
}
```
The `amount` is in USDC (= USD). Swap the USD amount for the tier you want. The swap converts your USDC to the equivalent $VAULT tokens at market rate.

### Step 3: Upgrade the subscription
```http
POST /v1/subscription/upgrade
Content-Type: application/json

{ "targetTier": "pro" }
```
The system fetches the current $VAULT price, calculates how many tokens = $20 USD, then atomically transfers 95% to treasury + burns 5%. On success returns `priceUsd`, `priceVault`, `vaultRate`, `newTier`, `txHash`, `burned`, `transferred`.

### Step 4: Verify
Confirm the response contains `success: true` and `newTier`. The transaction count resets to 0 and new limits are active immediately.

## Complete Decision Flow (follow this exactly)

1. `GET /v1/subscription` → check `status` and `transactions.percentage`
2. If `status` is `"near_limit"` or `"at_limit"` → upgrade is needed
3. Pick target tier from `upgradeOptions[]` (next tier up, or what user requested)
4. Check `canAfford` for that tier:
   - **true** → go to step 5
   - **false** → swap USDC → $VAULT first: `POST /v1/swap { "fromToken": "USDC", "toToken": "77UrDzChDJmSQbQDEjBGLmaKqyxbWiEEzSTtEWwbpump", "amount": "<priceUsd>" }`
5. `POST /v1/subscription/upgrade { "targetTier": "<tier>" }`
6. Verify `newTier` and `txHash` in response — tell user their new tier and limits

## Error Handling
- `INSUFFICIENT_BALANCE`: Not enough $VAULT → swap USDC → $VAULT first (step 2)
- `QUOTE_FAILED`: Could not fetch $VAULT price → retry in a moment
- `NO_SOLANA_VAULT`: Need a Solana vault → `POST /v1/vault/create { "chain": "solana" }`
- `INVALID_UPGRADE`: Already on same or higher tier (includes passing "free")
- `RPC_ERROR`: Solana RPC issue → retry after a moment
- `PAYMENT_FAILED`: On-chain transaction failed → check Solana vault has SOL for gas, retry

## MCP Tools

If using ClawVault via MCP (Model Context Protocol), these tools handle subscriptions:

- **`get_subscription`** — Check tier, usage, limits, $VAULT balance, and upgrade options with `canAfford` flags and market-rate pricing. Call proactively.
- **`upgrade_subscription`** — Pay for tier upgrade. Prices are in USD, automatically converted to $VAULT at market rate. If `canAfford` is false, swap USDC → $VAULT first using `swap_tokens`.
- **`swap_tokens`** — Swap USDC → $VAULT: `fromToken: "USDC"`, `toToken: "77UrDzChDJmSQbQDEjBGLmaKqyxbWiEEzSTtEWwbpump"`, `amount: "<USD amount>"`. The swap amount should match the tier's USD price.

---

# GOAT SDK (Programmable Actions)

The GOAT SDK provides a unified interface for all on-chain operations (swaps, transfers, liquidity, predictions, token ops). All GOAT actions go through the ClawVault rules engine before execution.

## 18. List GOAT Actions

```http
GET /v1/goat/actions
```

Returns all available GOAT SDK actions with their name, description, category, and plugin. Use this to discover what actions are available before executing.

## 19. Get Rules for GOAT Action Category

```http
GET /v1/goat/rules/{category}
```

| Param | Description |
|-------|-------------|
| `category` | Action category: `swap`, `transfer`, `liquidity`, `prediction`, `token_ops`, `unknown` |

Returns the rule definitions for the category plus the user's current config (enabled, maxAmount, requireApproval).

## 20. Execute GOAT Action

```http
POST /v1/goat/execute
Content-Type: application/json

{
  "action": "swap_tokens",
  "params": { "fromToken": "USDC", "toToken": "SOL", "amount": "10" }
}
```

| Field | Description |
|-------|-------------|
| `action` | GOAT action name (e.g. `swap_tokens`, `transfer_token_by_mint_address`) |
| `params` | Parameters for the action (object or JSON string) |

The action is validated against the user's rules engine before execution. Response: `{ success, status, data, reason, pendingId }` (top-level, not wrapped in `data` envelope).

### GOAT Execution Flow
1. Call `GET /v1/goat/actions` to see available actions
2. Optionally call `GET /v1/goat/rules/{category}` to check rules before executing
3. Call `POST /v1/goat/execute` with the action name and parameters
4. If rules block the action, the response includes the reason and which rule blocked it

---

# COMMON ENDPOINTS

## 21. Check Payment Status

```http
GET /v1/payments/{payment_id}
GET /v1/card/transactions/{transaction_id}
```

## 22. List Payments

```http
GET /v1/payments?limit=10&status=pending
GET /v1/card/transactions?limit=10
```

Optional `status` filter: `pending`, `auto_approved`, `manually_approved`, `blocked_by_rule`, `denied`, `expired`, `executed`, `failed`.

## 22a. List Agents

```http
GET /v1/agents
```

Returns all agents for the authenticated user with id, name, status, chain, provider, createdAt.

## 23. Get Current Rules

```http
GET /v1/rules
```

Returns all active rules including swap, prediction, card, and general limits.

## 23a. Update Rules

```http
PATCH /v1/rules
Content-Type: application/json

{
  "perTxLimit": "100.00",
  "sleepGuardStart": "23:00",
  "sleepGuardEnd": "07:00"
}
```

Update any rule field. Setting sleepGuardStart/End automatically enables the sleep guard. Returns the full updated rules object.

## 23b. Approve / Deny Payment

```http
POST /v1/payments/{payment_id}/approve
POST /v1/payments/{payment_id}/deny
```

Approve or deny a pending payment. Only works on payments with status `pending`. Approved payments execute on-chain immediately.

## 23c. Get Vault Balance

```http
GET /v1/vault/balance/{address}?chain=solana
```

Returns USDC balance, native token balance (SOL/ETH), and all token balances for Solana vaults.

## 23d. Withdraw from Vault

```http
POST /v1/vault/withdraw
Content-Type: application/json

{
  "vaultAddress": "8G8k...",
  "destination": "DRFMKrK...",
  "amount": "10.00",
  "chain": "solana",
  "token": "USDC"
}
```

Optional `token` field: `"USDC"` (default), `"SOL"` (Solana native), or SPL mint address.

---

# DECIDING WHICH CHANNEL TO USE

| Scenario | Use |
|----------|-----|
| Sending USDC to a blockchain address | Crypto (`/v1/payments`) |
| Swapping tokens on Solana (e.g. USDC to SOL) | Swap (`/v1/swap`) |
| Trading prediction markets (Kalshi) | Predictions (`/v1/prediction/buy`) |
| Paying for SaaS / API / cloud services | Card (`/v1/card/purchase`) |
| Paying for any online service or merchant | Card (`/v1/card/purchase`) |
| Programmatic on-chain actions via GOAT SDK | GOAT (`/v1/goat/execute`) |
| Need USDC but vault is empty | Credit (`/v1/credit/request`) |
| Accessing x402-gated APIs / paying for data | x402 (`/v1/x402/fetch`) |

**Rule of thumb**: Blockchain address = crypto. Token exchange = swap. Market outcome bet = prediction. Company/service = card. Programmatic/SDK actions = GOAT. Need to borrow = credit. x402-gated API = x402.

---

# COMMON SCENARIOS

### User asks to swap USDC for SOL
1. Call `/v1/swap/quote` to get a price quote
2. Show the user the quote (output amount, price impact)
3. If they confirm, call `/v1/swap` to execute
4. Return the explorer link: `https://solscan.io/tx/{txHash}`

### User asks about prediction markets
1. Call `GET /v1/prediction/wallet` first — check exists + KYC + balance
2. If no wallet → tell user to set up in dashboard. If no KYC → tell user to verify.
3. If wallet has 0 USDC → tell user to fund it via the ClawVault dashboard
4. Call `/v1/prediction/markets?status=active&search=keyword` to find markets
5. Show available markets with yes/no prices
6. If they want to buy, call `/v1/prediction/buy`
7. Check positions with `/v1/prediction/positions`

### User asks to pay for OpenAI API credits
1. Call `/v1/card/check` to verify it's allowed
2. If allowed, call `/v1/card/purchase`
3. If approved, use the card credentials at checkout immediately (they expire in 5 minutes)
4. If pending, tell user to approve in Telegram

### User asks to send USDC to an address
1. Call `/v1/rules/check` to see if it will auto-approve
2. Call `/v1/payments` with the recipient address
3. If pending, tell user to approve in Telegram

---

# AGENT CREDIT (ACE — Agent Credit Engine)

Borrow USDC on Solana when your vault balance is insufficient. Powered by Valeo's ACE.

- **Max per loan:** $10 (configurable via rules, up to $10)
- **Fee:** 3% per loan (e.g. borrow $5 → $0.15 fee)
- **Auto-repay:** ACE monitors on-chain and auto-repays when funds are available. ClawVault reconciles loan statuses with ACE on every status check and before new credit requests.
- **Solana only:** Credit is disbursed to your Solana vault

## Credit Flow
1. Enable credit: `POST /v1/credit/enable` (registers with ACE, stores aceAgentId)
2. Configure rules: `PATCH /v1/rules` with `creditEnabled`, `creditAutoRequest`, `creditMaxOutstanding`, `creditMaxPerLoan`
3. Request credit manually: `POST /v1/credit/request` — or let it auto-trigger on swap/prediction deficit
4. ACE disburses USDC to your Solana vault
5. ACE auto-repays when vault has sufficient balance
6. ClawVault automatically reconciles: queries ACE for repaid loans and updates local tracking

## Auto-Trigger Behavior
When `creditAutoRequest: true` and your vault has insufficient USDC for a swap or prediction trade, ClawVault automatically:
1. Calculates the deficit
2. Requests credit from ACE (capped at `creditMaxPerLoan`)
3. Waits for funds to arrive (up to 30s)
4. Proceeds with the original transaction

## 30. Enable Credit

```http
POST /v1/credit/enable
```

Registers your agent with ACE and enables the credit line. Requires a Solana vault.

### Response
```json
{
  "success": true,
  "data": {
    "aceAgentId": "ace_abc123",
    "creditEnabled": true,
    "walletAddress": "8G8k...",
    "maxOutstanding": 10,
    "feeRate": "3%"
  }
}
```

## 31. Disable Credit

```http
POST /v1/credit/disable
```

Disables credit (keeps ACE registration for re-enabling later).

## 32. Request Credit

```http
POST /v1/credit/request
Content-Type: application/json

{
  "amount": "5.00",
  "reason": "Need USDC for swap"
}
```

Explicitly request a credit loan. Subject to rules: `creditEnabled`, `creditMaxPerLoan`, `creditMaxOutstanding`.

### Response
```json
{
  "success": true,
  "data": {
    "status": "approved",
    "loanId": "loan_xyz",
    "amount": 5,
    "fee": 0.15,
    "walletAddress": "8G8k..."
  }
}
```

## 33. Get Credit Status

```http
GET /v1/credit/status
```

### Response
```json
{
  "success": true,
  "data": {
    "registered": true,
    "creditEnabled": true,
    "autoRequest": true,
    "outstanding": 5.15,
    "available": 4.85,
    "feeRate": "3%",
    "maxOutstanding": 10,
    "maxPerLoan": 10,
    "loans": [
      {
        "loanId": "loan_xyz",
        "amount": 5,
        "fee": 0.15,
        "status": "disbursed",
        "triggeredBy": "swap:SOL-USDC",
        "createdAt": "2026-03-14T10:00:00Z"
      }
    ]
  }
}
```

## 34. Get Credit History

```http
GET /v1/credit/history?limit=20
```

Returns all credit transactions (pending, disbursed, repaid).

## Credit Rules (via PATCH /v1/rules)

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `creditEnabled` | boolean | false | Enable/disable credit |
| `creditAutoRequest` | boolean | false | Auto-borrow on swap/prediction deficit |
| `creditMaxOutstanding` | number | 10 | Max total outstanding credit (USD) |
| `creditMaxPerLoan` | number | 10 | Max amount per loan (USD) |

## Credit Error Codes

| Code | Meaning | Action |
|------|---------|--------|
| `CREDIT_DISABLED` | Credit not enabled | Call POST /v1/credit/enable |
| `CREDIT_FAILED` | ACE request failed | Check reason field for details |
| `SOLANA_ONLY` | No Solana vault | Create Solana vault first |

---

# x402 PAYMENTS (HTTP 402 Protocol)

Pay for x402-gated APIs and services using USDC on Solana. ClawVault's rules engine gates every payment.

- **Protocol:** HTTP 402 Payment Required (x402 standard by Coinbase/PayAI)
- **Token:** USDC on Solana
- **Wallet:** Uses your Crossmint vault (preferred) or prediction wallet (fallback) for payment
- **Flow:** Agent calls URL → gets 402 → ClawVault checks rules → pays USDC → retries → returns data

## x402 Flow
1. Agent calls `POST /v1/x402/fetch` with target URL
2. ClawVault makes request to target URL
3. If 402, parses payment requirements (amount, payTo, network)
4. Rules engine checks: enabled, per-request limit, daily limit, domain whitelist, cooldown
5. Signs USDC transfer from prediction wallet
6. Retries request with PAYMENT-SIGNATURE header
7. Logs payment in transactions table
8. Returns the API response data

## 30. x402 Fetch

```http
POST /v1/x402/fetch
Content-Type: application/json

{
  "url": "https://api.example.com/paid-endpoint",
  "method": "GET",
  "headers": {},
  "body": null
}
```

### Response (paid)
```json
{
  "success": true,
  "data": {
    "status": 200,
    "paid": true,
    "amountUsd": 0.01,
    "domain": "api.example.com",
    "txHash": "5KtP...",
    "body": { "result": "premium data" },
    "paymentResponse": { "success": true, "transaction": "5KtP..." }
  }
}
```

### Response (no payment needed)
```json
{
  "success": true,
  "data": { "status": 200, "paid": false, "body": { "result": "free data" } }
}
```

## x402 Rules (via PATCH /v1/rules)

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `x402Enabled` | boolean | false | Enable/disable x402 payments |
| `x402PerRequestLimit` | number | 1 | Max per x402 payment (USD). 0 = no limit |
| `x402DailyLimit` | number | 10 | Daily x402 budget (USD). 0 = unlimited |
| `x402ApprovedDomains` | string[] | [] | Domain whitelist. Empty = all domains |
| `x402MaxPerDay` | number | 100 | Max x402 transactions per day. 0 = unlimited |
| `x402CooldownSeconds` | number | 0 | Min seconds between x402 payments. 0 = no cooldown |

## x402 Error Codes

| Code | Meaning | Action |
|------|---------|--------|
| `X402_DISABLED` | x402 payments not enabled | Set x402Enabled: true in rules |
| `X402_DOMAIN_NOT_APPROVED` | Domain not in whitelist | Add domain to x402ApprovedDomains |
| `X402_AMOUNT_EXCEEDED` | Exceeds per-request limit | Reduce payment or increase x402PerRequestLimit |
| `X402_DAILY_LIMIT` | Daily x402 budget exceeded | Wait or increase x402DailyLimit |
| `X402_TX_LIMIT` | Daily transaction count limit | Wait or increase x402MaxPerDay |
| `X402_COOLDOWN` | Must wait between payments | Wait for cooldown |
| `X402_NO_WALLET` | No Solana wallet | Create a Solana vault or prediction wallet |
| `X402_NO_SOLANA` | No Solana payment option | Target API doesn't support Solana x402 |
| `X402_PAYMENT_FAILED` | Payment transaction failed | Check balance and try again |

---

# CHAIN ABSTRACTION (CAB)

Deposit tokens on one EVM chain, spend on another — no bridging required.
Uses ZeroDev intents to pull USDC/USDT/WETH/ETH from any supported chain.

## Supported Chains
Base, Ethereum, Arbitrum, Polygon, BSC, Avalanche

## Supported Tokens
USDC, USDT, WETH, ETH (native)

## Endpoints

### GET /v1/cab/balance
Get your unified balance across all EVM chains.
Query params: `ownerKey` (required), `homeChain` (default: base), `vaultAddress`, `tokens` (comma-separated, default: USDC,USDT,WETH,ETH), `networks` (comma-separated chain IDs)

### POST /v1/cab/send
Send a cross-chain transfer. Tokens pulled from highest-balance chains automatically.
Body: `{ ownerKey, vaultAddress, to, amount, destinationChain, homeChain?, inputChain?, gasToken? }`
- `gasToken`: NATIVE (use chain native token), SPONSORED (dev pays), USDC, USDT, or omit (paid from input tokens)
- `inputChain`: force tokens from a specific chain (optional)

### POST /v1/cab/enable
Install the intent executor on an existing vault (one-time setup). New vaults have it pre-installed.
Body: `{ ownerKey, vaultAddress, chain? }`

## MCP Tools
- `get_cab_balance` — unified balance across chains
- `cab_send` — cross-chain transfer
- `cab_enable` — enable CAB on existing vault

## CAB Error Codes

| Code | Meaning | Action |
|------|---------|--------|
| `CAB_BALANCE_FAILED` | Failed to fetch cross-chain balance | Check ownerKey and homeChain config |
| `CAB_SEND_FAILED` | Cross-chain transfer failed | Check balance, destination chain, and amount |
| `CAB_ENABLE_FAILED` | Failed to install intent executor | Verify vault address and owner key |

## How It Works
1. Kernel smart accounts have the same address across all EVM chains (deterministic CREATE2)
2. Deposit USDC to your vault address on any supported chain
3. Call `GET /v1/cab/balance` to see unified balance
4. Call `POST /v1/cab/send` to spend — ZeroDev solvers fill the intent cross-chain
5. No bridging, no manual token transfers between chains

---

# ERROR HANDLING

| Code | Meaning | Action |
|------|---------|--------|
| `INVALID_KEY` | Bad API key | Check your API key |
| `TIER_LIMIT_EXCEEDED` | Monthly limit reached | User needs to upgrade plan |
| `INSUFFICIENT_BALANCE` | Not enough funds | User needs to deposit (crypto) or fund card |
| `RULE_VIOLATION` | Outside allowed parameters | Check the `reason` field |
| `SWAP_FAILED` | Swap execution failed | Check token pair, amount, or try again |
| `PREDICTION_FAILED` | Prediction trade failed | Check market ticker, status, or balance |
| `NO_PREDICTION_WALLET` | No prediction wallet set up | User needs to create one in dashboard |
| `KYC_REQUIRED` | Prediction wallet needs KYC | User must complete dFlow Proof KYC in dashboard |
| `MARKET_UNAVAILABLE` | Market lacks on-chain tokens | Try a different market |
| `MARKET_NOT_FOUND` | Ticker not found | Check the market ticker spelling |
| `AMOUNT_TOO_SMALL` | Below minimum trade amount | Increase amount (minimum typically $1) |
| `MARKET_CLOSED` | Market no longer active | Market is finalized/closed/settled |
| `MARKET_NOT_SETTLED` | Market not yet settled | Redemption requires determined/finalized status |
| `NO_POSITION` | No tokens to sell/redeem | User may not hold a position in this market |
| `INVALID_AMOUNT` | Amount is not a valid number | Must be a positive number (string or number) |
| `INVALID_CONTENT_TYPE` | Wrong Content-Type header | Use Content-Type: application/json |
| `CARD_FROZEN` | Card is frozen | User needs to unfreeze in dashboard |
| `MERCHANT_BLOCKED` | Merchant category not allowed | Cannot purchase from this merchant |
| `CARD_NOT_ACTIVE` | Card not set up | User needs to apply for Agent Card |
| `GOAT_ERROR` | GOAT SDK action failed | Check action name, params, or try again |
| `INVALID_CATEGORY` | Invalid GOAT rule category | Use: swap, transfer, liquidity, prediction, token_ops, unknown |
| `UNAUTHORIZED` | Missing or invalid API key | Check Authorization header (Bearer cv_live_xxx) |
| `WRONG_KEY_TYPE` | Using partner key on agent endpoint or vice versa | Partner keys use /v1/partner/*; agent keys use all other endpoints |
| `MISSING_FIELDS` | Required fields missing from request | Check the endpoint's required parameters |
| `NOT_FOUND` | Resource not found | Check payment ID, agent ID, or address |
| `BAD_STATUS` | Invalid status for operation | e.g. can't approve a non-pending payment |
| `INVALID_CHAIN` | Unsupported blockchain | Supported: base, ethereum, arbitrum, polygon, bnb, avalanche, solana |
| `INVALID_ADDRESS` | Address format wrong for chain | EVM = 0x + 40 hex chars; Solana = base58 |
| `INVALID_SLIPPAGE` | Negative slippage value | Must be >= 0 (percentage: 0.5 = 0.5%, 3 = 3%) |
| `INVALID_VALUE` | Rule value out of range | Check field constraints (e.g. HH:MM format, non-negative) |
| `CAB_BALANCE_FAILED` | Failed to fetch chain-abstracted balance | Check ownerKey and homeChain |
| `CAB_SEND_FAILED` | Cross-chain transfer failed | Check balance, destination, amount |
| `CAB_ENABLE_FAILED` | Intent executor installation failed | Verify vault address and owner key |
| `INVALID_PAIR` | Same token swap | Cannot swap a token to itself |
| `QUOTE_FAILED` | Swap quote failed | Check token symbols and amount |
| `SLEEP_GUARD` | Outside allowed trading hours | Wait until the sleep guard window ends |
| `BALANCE_FAILED` | Balance lookup failed | Address may be invalid or provider unavailable |
| `CREDIT_DISABLED` | Credit not enabled | Call POST /v1/credit/enable first |
| `CREDIT_FAILED` | ACE credit request failed | Check reason field for details |

---

# BEST PRACTICES

1. **Always check first** — Use dry-run endpoints (`/v1/rules/check`, `/v1/card/check`, `/v1/swap/quote`) before executing
2. **Explain to users** — If approval is needed, tell them where to approve (Telegram or dashboard)
3. **Handle pending** — Don't assume transactions complete immediately
4. **Use card credentials immediately** — They expire in 5 minutes
5. **Show explorer links** — Crypto/swap/prediction txs link to `https://solscan.io/tx/{txHash}` (Solana) or `https://basescan.org/tx/{txHash}` (Base)
6. **Choose the right channel** — Blockchain address = crypto. Token exchange = swap. Market bet = prediction. Service/merchant = card.

---

# SUPPORT

- Dashboard: https://clawvault.cc
- Docs: https://clawvault.cc/docs
- API Status: https://api.clawvault.cc/health

---

# PARTNER API (Developer Platform)

For platforms and projects integrating ClawVault as their wallet + security layer. Requires a `cv_partner_` API key.

## Partner Authentication
```
Authorization: Bearer cv_partner_xxxxx
```

## 24. Onboard an Agent (One Call)

```http
POST /v1/partner/onboard
Content-Type: application/json

{
  "externalUserId": "user_abc123",
  "chain": "solana",
  "agentName": "Trading Bot #42",
  "rulesPreset": "balanced"
}
```

Creates user + wallet + agent + rules in one call. Returns API key for the new agent.
Idempotent: same `externalUserId` returns existing agent (with `existing: true` flag). Note: if the agent was previously deleted/revoked, re-onboarding returns the existing record but does NOT reactivate it — the API key remains blocked. To get a new active agent, use a different `externalUserId`.
Presets: `lockdown`, `balanced`, `power_user`

## 25. List Partner Agents

```http
GET /v1/partner/agents?limit=20&offset=0
```

## 26. Get Agent Detail

```http
GET /v1/partner/agents/{agent_id}
```

## 27. Freeze / Unfreeze Agent

```http
POST /v1/partner/agents/{agent_id}/freeze
POST /v1/partner/agents/{agent_id}/unfreeze
```

## 28. Revoke Agent

```http
DELETE /v1/partner/agents/{agent_id}
```

## 29. Partner Usage Stats

```http
GET /v1/partner/usage
```

Returns: totalAgents, activeAgents, frozenAgents, revokedAgents, totalTransactions, totalSpent.