Payments

The payments system provides transaction tracking, automatic bank notification detection, x402 micropayments, and Stripe card payments.

Overview

Payments in Uranus consists of four components:

• Transaction Tracking — Record and query payments with balance tracking
• Bank Notification Detection — Automatically parse bank SMS/email into transactions
• x402 Micropayments — Gate API endpoints behind HTTP 402 paywalls
• Stripe Payments — Checkout sessions, virtual issuing cards, and charge management

Transaction Tracking

LLM Tools

The agent has access to five payment tools:

Tool	Description
check_balance	Query current wallet balance
list_transactions	List transactions with optional filters
log_payment	Manually record a payment
send_payment	Initiate an outbound payment
list_payment_methods	List configured payment methods

Payment Methods

Payment methods are stored per agent and can be managed via the dashboard or API. Each method includes:

• Type — Card, bank account, wallet, etc.
• Label — User-friendly name
• Details — Method-specific configuration

curl -X POST https://your-domain.com/api/agents/{id}/payment-methods \
  -H "Content-Type: application/json" \
  -d '{
    "type": "wallet",
    "label": "USDC Wallet",
    "details": {
      "address": "0x...",
      "network": "base"
    }
  }'

Bank Notification Auto-Detection

The system intercepts incoming gateway messages (SMS, email, WhatsApp) and checks for bank payment notifications before they reach the LLM.

How It Works

1. Keyword matching — Messages are scanned against a set of financial keywords (e.g., "credited", "debited", "transfer", "balance"). A minimum of 2 keyword matches triggers detection.
2. LLM parsing — Matched messages are sent to Workers AI for structured extraction of amount, currency, sender/receiver, reference number, and date.
3. Transaction creation — Parsed data is automatically saved to the transactions table with the source gateway and original message linked.

┌──────────────┐     ┌───────────────────┐     ┌──────────────┐
│   Gateway    │────▶│ Keyword Detection  │────▶│  Workers AI  │
│  (SMS/Email) │     │  (2+ matches)      │     │  (LLM Parse) │
└──────────────┘     └───────────────────┘     └──────┬───────┘
                                                       │
                                                       ▼
                                               ┌──────────────┐
                                               │ transactions │
                                               │    table     │
                                               └──────────────┘

Detected notifications are also stored in the payment_notifications table with a matched or unmatched status indicating whether they were successfully parsed.

x402 Micropayments

x402 implements the x402.org protocol for HTTP 402-based micropayments.

Gated Endpoints

Create resources that require payment before access:

curl -X POST https://your-domain.com/api/agents/{id}/x402-resources \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/rpc/premium-analysis",
    "price": "0.01",
    "currency": "USDC",
    "network": "base",
    "description": "Premium market analysis"
  }'

How It Works

1. A client calls a gated /rpc endpoint
2. The checkX402PaymentGate middleware intercepts the request
3. If no payment is attached, the server returns HTTP 402 with payment requirements:

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "10000",
    "resource": "https://your-domain.com/api/agents/{id}/rpc/premium-analysis",
    "description": "Premium market analysis",
    "payTo": "0x..."
  }]
}

4. The client submits payment and retries with a payment proof header
5. The middleware verifies payment via the Coinbase facilitator and allows the request through
6. A transaction is logged with type x402

Supported Networks

Network	Currency
Base	USDC
Avalanche	USDC
Solana	USDC

Stripe Integration

Checkout Sessions

Create hosted checkout pages for one-time or subscription payments:

curl -X POST https://your-domain.com/api/agents/{id}/stripe/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000,
    "currency": "usd",
    "description": "Pro Plan",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
  }'

Issuing Virtual Cards

Create and manage Stripe Issuing virtual cards for agent spending:

• Create cards with spending limits
• Freeze/unfreeze cards on demand
• Track authorizations in real time

LLM Tools

Tool	Description	Requires Approval
create_checkout	Create a Stripe checkout session	Yes
charge_card	Charge a virtual issuing card	Yes

Approval Threshold

Configure requireApprovalAbove in payment settings to allow the agent to autonomously charge amounts below the threshold. Charges above the threshold require human approval via the Human-in-the-Loop system.

Webhook Processing

Set your Stripe webhook endpoint to:

https://your-domain.com/api/agents/{id}/stripe/webhook

Processed events:

Event	Action
checkout.session.completed	Logs transaction, updates session status
issuing_authorization.request	Approves or declines based on settings
charge.succeeded	Logs completed charge transaction

Webhook signatures are verified using HMAC-SHA256 with your Stripe webhook secret.

Payment Settings

Configure payments under Settings > Payments:

Setting	Description
walletAddress	Default crypto wallet address
walletNetwork	Default blockchain network
defaultCurrency	Default currency for transactions
stripeSecretKey	Stripe API secret key
stripePublishableKey	Stripe publishable key
stripeWebhookSecret	Stripe webhook signing secret
x402.enabled	Enable x402 micropayments
x402.facilitatorUrl	Coinbase facilitator endpoint
requireApprovalAbove	Auto-approve charges below this amount

Dashboard

Navigate to Payments in the sidebar to access the payments UI. The page has six tabs:

1. Transactions — View and filter all transactions
2. Balance — Current balance summary
3. Payment Methods — Manage wallets and cards
4. Notifications — Bank notification detection log
5. x402 Resources — Manage gated endpoints
6. Stripe — Checkout sessions and issuing cards

API Reference

See Payments API for complete endpoint documentation.