API Documentation

Overview

This platform enables autonomous agent-to-agent payments using x402 and MPP (Machine Payments Protocol). It handles both sides of the transaction:

Authentication

All buyer API requests use the X-Agent-Key header. Generate API keys from the agent detail page. Each key is scoped to a single agent and can be revoked at any time.

X-Agent-Key: ak_live_abc123...

POST /api/agents/{id}/pay

Initiate a payment to a seller endpoint. The platform calls the seller URL, handles the 402 negotiation (x402 or MPP, auto-detected from the seller's response headers), signs the payment, and returns the seller's response.

Request Body

{
  "sellerUrl": "https://api.example.com/resource",
  "method": "GET",          // optional, defaults to GET
  "headers": {},            // optional, extra headers to forward
  "body": ""                // optional, request body for POST/PUT
}

Success Response (200)

{
  "success": true,
  "sellerResponse": { ... },
  "payment": {
    "protocol": "x402",
    "txHash": "0xabc...",
    "amount": "0.01",
    "explorer": "https://testnet.radiustech.xyz/tx/0xabc...",
    "transactionId": "clxyz..."
  },
  "agent": {
    "address": "0x1234..."
  }
}

Error Responses

Webhooks

Configure webhook endpoints from the agent detail page to receive real-time notifications about payment events. Each webhook includes an HMAC-SHA256 signature in the X-Webhook-Signature header.

Event Types

• payment.confirmed — Payment confirmed on-chain
• payment.failed — Payment failed during execution
• payment.rejected — Payment rejected by spending controls

Signature Verification

import crypto from "crypto";

function verifyWebhook(payload: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Spending Limits

Each agent supports three tiers of spending controls, all denominated in SBC:

• Per-transaction limit — Maximum amount for a single payment. Set to 0 for no limit.
• Daily limit — Maximum total spending per calendar day (resets at midnight UTC).
• Monthly limit — Maximum total spending per calendar month.

Limits are enforced server-side before any on-chain transaction is signed. If a payment would exceed any configured limit, the request is rejected with the corresponding error code.

Policy Rules

Policy rules provide additional spending controls beyond the basic limits. Manage them from the agent detail page or via the /api/agents/{id}/policy-rules endpoint (dashboard auth required).

Rule Types

• max_amount — Cap the maximum payment amount
• time_restriction — Restrict payments to specific hours or days
• per_seller_cap — Limit total spending per individual seller address

Rules can be toggled active/inactive without deleting them. Only active rules are enforced during payment processing.

Testing

Use the "Test Buy" button on the agent detail page to make a test payment against the built-in demo seller:

GET /api/demo/seller

This endpoint simulates a 402 paywall that charges a small amount of SBC on testnet, returning mock data upon successful payment.