dingdawg-x402-pay — Governed AI Agent Payments

Budget gates and audit trails for x402 stablecoin micropayments

AI agents are spending money autonomously. Without governance, that means unchecked spend, zero audit trails, and no policy enforcement. dingdawg-x402-pay wraps every payment in a governance layer — budget gates, spend policies, and SHA-256 chained receipts — before a single USDC moves.

Quick Start

npx dingdawg-x402-pay

Or install globally:

npm install -g dingdawg-x402-pay
dingdawg-x402-pay

Add to Claude Code

{
  "mcpServers": {
    "dingdawg-x402-pay": {
      "command": "npx",
      "args": ["dingdawg-x402-pay"]
    }
  }
}

Add to Cursor

In Cursor Settings → MCP:

{
  "mcpServers": {
    "dingdawg-x402-pay": {
      "command": "npx",
      "args": ["dingdawg-x402-pay"]
    }
  }
}

How It Works

Agent requests payment
       │
       ▼
authorize_payment — governance check
  ├── Is the tool allowed by policy?
  ├── Is the amount within per-call limit?
  └── Is there enough daily budget remaining?
       │
  ┌────┴────────────────────┐
DENIED                 AUTHORIZED
Return reason     Return auth token + receipt_id
                       │
                       ▼
              x402 payment executes
              (USDC → tool provider)
                       │
                       ▼
            payment_receipt — finalize
  ├── Validates auth token (5-min TTL)
  ├── Deducts spend from agent budget
  ├── SHA-256 chains receipt to prior receipts
  └── Writes immutable audit entry

Every payment is receipted. Every denial is logged. No gaps.

Tools

authorize_payment

Check budget policy before an x402 payment executes.

Input:

{
  "amount_usdc": 0.05,
  "recipient": "0xRecipientAddress",
  "tool_name": "web-search",
  "agent_id": "agent_prod_001"
}

Returns (authorized):

{
  "authorized": true,
  "authorization_token": "auth_abc123...",
  "receipt_id": "rcpt_xyz456...",
  "amount_usdc": 0.05,
  "expires_at": "2025-01-01T00:05:00Z"
}

Returns (denied):

{
  "authorized": false,
  "reason": "Amount 5.00 USDC exceeds per-call limit of 1.00 USDC.",
  "policy_id": "pol_default"
}

check_budget

Query remaining budget for an agent or team.

Input:

{ "agent_id": "agent_prod_001" }

Returns:

{
  "agent_id": "agent_prod_001",
  "budget_total": 10.0,
  "budget_spent": 1.25,
  "budget_remaining": 8.75,
  "policy_name": "default",
  "max_per_call": 1.0,
  "max_daily": 10.0,
  "reset_at": "2025-01-02T00:00:00Z"
}

payment_receipt

Finalize a completed payment. Produces a SHA-256 chained audit entry.

Input:

{
  "payment_hash": "0xTxHash...",
  "amount": 0.05,
  "recipient": "0xRecipientAddress",
  "tool_used": "web-search",
  "authorization_token": "auth_abc123..."
}

Returns:

{
  "receipt_id": "rcpt_xyz456...",
  "sha256_chain": "a3f7b2...",
  "governance_decision": "AUTHORIZED",
  "audit_entry": "Agent agent_prod_001 paid 0.05 USDC to 0xRecipient for tool \"web-search\" at 2025-01-01T00:01:00Z.",
  "budget_remaining": 8.70
}

set_policy

Define a spending policy with per-call limits, daily caps, and tool controls.

Input:

{
  "policy_name": "conservative",
  "max_per_call": 0.10,
  "max_daily": 2.00,
  "allowed_tools": ["web-search", "code-interpreter"],
  "blocked_tools": ["image-gen"]
}

Returns:

{
  "policy_id": "pol_abc123...",
  "policy_name": "conservative",
  "max_per_call": 0.10,
  "max_daily": 2.00
}

audit_payments

Query full payment history with governance data and spend totals.

Input:

{
  "agent_id": "agent_prod_001",
  "date_range": { "from": "2025-01-01", "to": "2025-01-31" },
  "min_amount": 0.01
}

Returns:

{
  "total_records": 42,
  "total_spent_usdc": 3.15,
  "authorized_count": 40,
  "denied_count": 2,
  "payments": [...]
}

For AI Assistants

This tool is designed for agent-to-agent composability. All outputs are structured JSON.

Recommended flow:

1. Call check_budget before any payment to confirm headroom.
2. Call authorize_payment with the exact amount, recipient, and tool name.
3. If authorized: true, proceed with the x402 payment using the returned authorization_token.
4. After settlement, call payment_receipt with the payment_hash and authorization_token to finalize the audit trail.
5. Call audit_payments to surface spend summaries for reporting or policy review.

Authorization tokens expire in 5 minutes. Complete the payment flow without delay.

Budget resets are daily. Call check_budget at the start of any long-running agent run.

Pricing

The governance layer is free. Payments flow in USDC directly from the agent to the tool provider — no middleman, no markup. You pay for the tools you use, not for the governance that protects you.

Architecture

dingdawg-x402-pay is a thin governance wrapper. It does not hold wallets, sign transactions, or touch funds. In v1 it uses an in-process store for budget and receipt state. In v2, all governance checks route to the DingDawg governance API for persistent multi-session state, team dashboards, and webhook alerts.

Your Agent
    │
    ▼
dingdawg-x402-pay (MCP)    ←── governance rules, budget state
    │
    ▼
x402 Payment Rail           ←── USDC settlement (Base, Ethereum, etc.)
    │
    ▼
Tool Provider

Requirements

• Node.js 18+
• Any MCP-compatible host (Claude Code, Cursor, Claude Desktop, custom)

Links

• Website: dingdawg.com
• npm: npmjs.com/package/dingdawg-x402-pay
• Issues: github.com/dingdawg/dingdawg-x402-pay/issues

License

MIT © DingDawg