ClawVault Payments

intent

clawvault payments is a security middleware that sits between your AI agent and real money. it protects two spending channels: USDC transfers on Base and Solana blockchains, and virtual Visa cards for any merchant worldwide. every transaction runs through a rules engine (spending limits, whitelists, time windows). transactions that pass auto-approve and execute; anything outside your rules gets held for human approval via Telegram or dashboard. use this skill when your agent needs to pay for services, send crypto, or purchase subscriptions without giving it full access to your keys or card.

inputs

• CLAWVAULT_API_KEY (environment variable, required): your api key in format cv_live_xxxxx. generate one at https://clawvault.cc/agents. all http requests must include Authorization: Bearer ${CLAWVAULT_API_KEY} header.
• api base url: https://api.clawvault.cc (all endpoints POST or GET to this base).
• vault setup (prerequisite): at least one crypto wallet connected (Base or Solana) with USDC balance, or Agent Card activated for Visa transactions.
• telegram or dashboard access (for approval notifications): user must have Telegram bot enabled or dashboard access to approve pending transactions.
• network connectivity: agent must reach api.clawvault.cc over https without proxy/firewall blocking.

procedure

step 1: check api health and authenticate

• input: CLAWVAULT_API_KEY from environment.
• action: make GET request to https://api.clawvault.cc/health with no auth header to confirm api is online. then make GET request to https://api.clawvault.cc/v1/vault with Authorization: Bearer ${CLAWVAULT_API_KEY} to verify api key is valid.
• output: {"success": true} with vault data if auth passes. if auth fails, {"success": false, "error": {"code": "INVALID_KEY"}}.
• error handling: if api is offline (500+), retry with exponential backoff up to 5 attempts. if api key is invalid, log error and stop. do not retry bad keys.

step 2: determine payment channel (crypto vs card)

• input: user's payment request (recipient address, merchant name, amount, currency).
• action: inspect recipient. if it matches blockchain address pattern (0x followed by 40 hex chars on Ethereum-compatible chains, or base58 on Solana), route to crypto channel. if recipient is a company/service name or merchant category, route to card channel.
• output: decision flag: channel = "crypto" or channel = "card".
• reference table: blockchain address → crypto. SaaS, APIs, cloud services, online merchants → card.

step 3a (crypto path): check crypto payment rules before execution

• input: amount (USD string, e.g., "50.00"), token ("USDC"), recipient (0x address), chain ("base" or "solana"), reason (transaction context).
• action: POST to https://api.clawvault.cc/v1/rules/check with json body:

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

• output: response object with fields: allowed (bool), autoApprove (bool), reason (string), remainingBudget (object with daily/weekly/monthly keys), remainingTx (object with daily/weekly/monthly keys).
• edge cases: if remainingBudget.daily is 0 or less, transaction will not auto-approve. if remainingTx.daily is 0 or less, user has hit tx count limit.

step 3b (crypto path): execute crypto payment

• input: validated amount, token, recipient, chain, reason, rule check result from step 3a.
• action: POST to https://api.clawvault.cc/v1/payments with json body:

  {
    "amount": "50.00",
    "token": "USDC",
    "recipient": "0x1234567890abcdef...",
    "chain": "base",
    "reason": "Payment for services rendered",
    "skill": "transfer"
  }
  

• output: response with id (payment id, e.g., "pi_abc123"), status (one of: "auto_approved", "pending", "denied", "expired"), expiresAt (ISO 8601 timestamp for approval window, typically 5 minutes from request time).
• status behavior:
  • auto_approved: transaction has executed on-chain immediately. inform user of transaction id and chain. optionally provide link to block explorer (e.g., basescan.org for Base).
  • pending: transaction is awaiting human approval. inform user to check Telegram bot or ClawVault dashboard within 5 minutes.
  • denied: transaction was rejected by rules engine or user. inform user with reason field if provided.
  • expired: approval window closed (user did not approve in time). suggest user retry.
• network timeouts: if POST to /v1/payments times out (>30s), retry up to 2 times with 5s backoff. if all retries fail, inform user that the request could not be confirmed and suggest checking dashboard.

step 4a (card path): check card purchase rules before execution

• input: amount (float, e.g., 20.00), merchant_category (string, e.g., "api_services", "saas", "cloud_compute").
• action: POST to https://api.clawvault.cc/v1/card/check with json body:

  {
    "amount": 20.00,
    "merchant_category": "api_services"
  }
  

• output: response with fields: allowed (bool), autoApprove (bool), reason (string, e.g., "Within limits, allowed category").
• edge cases: if allowed: false, transaction will be denied. do not proceed to step 4b.

step 4b (card path): request virtual card credentials

• input: amount (float), currency ("USD"), merchant (string), merchant_category (string), reason (string for audit trail).
• action: POST to https://api.clawvault.cc/v1/card/purchase with json body:

  {
    "amount": 20.00,
    "currency": "USD",
    "merchant": "OpenAI API",
    "merchant_category": "api_services",
    "reason": "GPT-4 API credits for research task"
  }
  

• output: response with id (transaction id), status (either "approved" or "pending_approval"), and if status is "approved", a nested card_credentials object with fields: number (PAN, 16 digits), exp_month (1-12), exp_year (4-digit year), cvc (3-4 digit security code), valid_for_seconds (typically 300 = 5 minutes).
• status behavior:
  • approved: card credentials are valid and ready to use. inform user of transaction id. proceed to step 4c immediately (credentials expire in 5 minutes).
  • pending_approval: user must approve in Telegram or dashboard. do not use credentials. inform user to check Telegram or dashboard within 5 minutes. optionally poll /v1/card/transactions/{transaction_id} every 10 seconds up to 30 times (5 minutes total) to detect approval completion.
• credential security: card credentials are sensitive. never log them, never store them, never send them to logs or external services. use them immediately at merchant checkout and discard.

step 4c (card path): use card credentials immediately

• input: card credentials from step 4b (number, exp_month, exp_year, cvc), merchant checkout url or form.
• action: apply credentials to merchant's payment form (e.g., stripe checkout, payment gateway, subscription page). submit payment. credentials expire in 5 minutes, so complete this step within that window.
• output: merchant accepts or rejects the card. if accepted, payment is processed. if rejected (e.g., insufficient funds, cvv mismatch, card flagged), merchant returns error; inform user with merchant's error message.
• edge case: if merchant rejects the card but the transaction was already "approved" by ClawVault, inform user that ClawVault approved it but the merchant declined. suggest contacting merchant or checking card balance.

step 5: check vault status and balances

• input: none (requires CLAWVAULT_API_KEY).
• action: GET to https://api.clawvault.cc/v1/vault with Authorization header.
• output: response with fields: chain (e.g., "base"), balances (array of objects with token and balance strings), rules (object with mode, perTxLimit, dailyTxMax, etc.).
• use case: call this before suggesting a payment to confirm vault has sufficient balance. if balance is 0 or less than requested amount, inform user that vault needs funding.

step 6: check card balance and limits

• input: none (requires CLAWVAULT_API_KEY).
• action: GET to https://api.clawvault.cc/v1/card/balance with Authorization header.
• output: response with fields: balance (available balance, float), currency ("USD"), spent_today (float), spent_this_month (float), daily_limit (float), monthly_limit (float).
• use case: call this before a card purchase to confirm available balance and remaining daily/monthly allowance. inform user if balance is insufficient or if purchase would exceed daily/monthly limit.

step 7: poll or fetch transaction status

• input: payment_id (from step 3b) or transaction_id (from step 4b).
• action: GET to https://api.clawvault.cc/v1/payments/{payment_id} (for crypto) or https://api.clawvault.cc/v1/card/transactions/{transaction_id} (for card) with Authorization header.
• output: response with current status (auto_approved, pending, denied, expired, etc.), timestamps, and optional on-chain data (txHash, block number for crypto).
• polling strategy: for pending transactions, poll every 10 seconds for up to 5 minutes. if status does not change after 5 minutes, consider it expired and inform user.

step 8: list recent transactions

• input: limit (integer, default 10, max 100), optional filters (chain, status, merchant).
• action: GET to https://api.clawvault.cc/v1/transactions?limit=10 or https://api.clawvault.cc/v1/card/transactions?limit=10 with Authorization header.
• output: response with array of transaction objects (id, amount, status, timestamp, recipient/merchant, reason).
• use case: audit trail, confirm recent payments, troubleshoot failed transactions.

decision points

if recipient is a blockchain address (0x... or base58 solana address): use crypto channel (steps 3a, 3b). skip card steps.

if recipient is a merchant or service name: use card channel (steps 4a, 4b, 4c). skip crypto steps.

if rules check returns allowed: false: do not proceed with the payment or purchase. inform user that the transaction violates spending rules. check the reason field for details (e.g., "exceeds daily limit", "merchant category not whitelisted").

if autoApprove: true (from rules check): transaction will auto-execute or auto-approve. proceed immediately to execute payment (step 3b) or purchase (step 4b). no human approval needed.

if autoApprove: false (from rules check): transaction will require human approval. inform user that approval is needed and direct them to Telegram bot or dashboard. set a 5-minute timeout for approval. if user does not approve within 5 minutes, the transaction expires and must be retried.

if transaction status is "pending" (from execution response): transaction is awaiting approval. do not assume it has completed. inform user to check Telegram or dashboard. optionally poll the status endpoint every 10 seconds up to 5 minutes.

if transaction status is "denied": transaction was rejected. inform user with the reason provided. do not retry automatically.

if transaction status is "expired": approval window closed without user action. inform user and offer to retry if desired.

if vault balance < requested amount (from step 5): transaction will fail. inform user that vault needs funding. do not attempt the payment.

if card balance < requested amount (from step 6): transaction will fail. inform user that card needs funding or top-up. do not attempt the purchase.

if api returns INVALID_KEY error: api key is missing, malformed, or revoked. stop all requests. inform user to generate a new api key at https://clawvault.cc/agents.

if api returns TIER_LIMIT_EXCEEDED error: user's account has hit monthly spending cap. inform user to upgrade their ClawVault plan or contact support.

if api returns CARD_NOT_ACTIVE error: user has not applied for or activated the Agent Card. inform user to visit dashboard and apply for the card.

if api returns CARD_FROZEN error: card is frozen (likely due to suspicious activity). inform user to unfreeze it in the dashboard or contact support.

if api returns MERCHANT_BLOCKED error: merchant category is not whitelisted. inform user that this merchant cannot be paid via card. user must update their card rules in dashboard if they want to allow it.

if api returns INSUFFICIENT_BALANCE error: vault (for crypto) or card (for card) has insufficient funds. inform user to deposit or fund the account.

if network request times out (>30s): retry up to 2 times with 5-second backoff. if all retries fail, inform user that the request could not be confirmed and suggest checking the ClawVault dashboard.

if user approves a pending transaction: status will change from "pending" to "auto_approved" (for pending approvals that did not execute immediately). crypto transactions then execute on-chain. card transactions then provide credentials for use at checkout.

if user denies a pending transaction: status will change to "denied". inform user that the transaction has been cancelled.

output contract

• for crypto payments (auto_approved): agent receives payment_id (string, e.g., "pi_abc123"), status: "auto_approved", and optional txHash (on-chain transaction hash). transaction is confirmed on Base or Solana. agent should provide user with transaction id and link to block explorer (e.g., https://basescan.org/tx/{txHash} for Base).

• for crypto payments (pending): agent receives payment_id, status: "pending", and expiresAt (ISO 8601 timestamp, 5 minutes from request). transaction id is held in ClawVault vault. agent must inform user to approve in Telegram or dashboard within 5 minutes.

• for card purchases (approved): agent receives transaction_id, status: "approved", and card_credentials object with fields: number (16-digit PAN), exp_month (1-12), exp_year (4-digit), cvc (3-4 digit security code), valid_for_seconds (300 = 5 minutes). agent must use credentials immediately at merchant checkout.

• for card purchases (pending_approval): agent receives transaction_id, status: "pending_approval", and optional reason string. no credentials are provided. agent must inform user to approve in Telegram or dashboard within 5 minutes. if approved, agent must re-fetch transaction to retrieve credentials.

• for vault status: agent receives object with chain (string, e.g., "base"), balances (array of {token, balance}), rules (object with mode, perTxLimit, dailyTxMax, etc.).

• for card balance: agent receives object with balance (float, USD), spent_today (float), spent_this_month (float), daily_limit (float), monthly_limit (float).

• for transaction list: agent receives array of transaction objects (id, amount, status, timestamp, recipient/merchant, reason, etc.).

• all error responses follow format: {"success": false, "error": {"code": "ERROR_CODE", "message": "human-readable error message"}}.

outcome signal

• crypto payment succeeded: user sees transaction id (e.g., "pi_abc123"), confirmation that funds have been sent to the recipient address, and optional link to block explorer showing on-chain confirmation.

• crypto payment pending approval: agent tells user "this transaction needs your approval. check your telegram bot or clawvault dashboard." user navigates to Telegram or dashboard and sees a pending approval prompt with amount, recipient, and reason. user taps "approve" or "deny". if approved, agent confirms execution to user. if denied, agent tells user the transaction was cancelled.

• card purchase succeeded: user sees transaction id, confirmation that the merchant has charged the card, and a receipt or confirmation from the merchant.

• card purchase pending approval: agent tells user "this purchase needs your approval. check your telegram bot or clawvault dashboard." user approves via Telegram or dashboard. agent retrieves card credentials and completes checkout. user receives confirmation from merchant.

• card purchase failed: agent tells user why the purchase was declined (e.g., "insufficient card balance", "merchant category blocked", "exceeds daily limit"). user can check ClawVault dashboard for details and retry or update spending rules.

• transaction list retrieved: agent has complete audit trail of recent payments and purchases. user can see transaction history, amounts, statuses, and timestamps.

• vault or card balance checked: user sees current available balance, daily/monthly spend, and remaining budget. agent uses this info to confirm sufficient funds before executing a payment or purchase.

• any api request fails: agent logs error code and message. if error is recoverable (timeout, rate limit), agent retries. if error is terminal (invalid key, rule violation), agent stops and informs user with actionable next step (e.g., "check your api key", "update your spending rules", "fund your account").

credits

original source: https://github.com/andrewszk/clawvault-mcp-server (clawhub). enriched and restructured to implexa standards with explicit decision points, edge cases, network handling, and outcome signals.