Documentation

AgentPayAPI provides risk-first infrastructure for autonomous AI transactions. Give your AI agents the ability to transact on-chain with hard cryptographic limits, ensuring they can operate autonomously without risking your entire treasury.

Quickstart

Install the official Node.js SDK via npm, yarn, or pnpm:

Initialize the client and execute your first transaction:

import { AgentPay } from '@agentpay/sdk';// Initialize with your API keyconst client = new AgentPay(process.env.AGENTPAY_API_KEY);// Execute a transactionconst receipt = await client.execute({ to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e', value: '0.05', // ETH chain: 'base'});console.log(`Transaction successful: ${receipt.hash}`);

Authentication

Authenticate your API requests using your secret API key. You can generate and manage API keys in the Dashboard.

Pass the API key to the SDK constructor, or set it as an environment variable AGENTPAY_API_KEY. Never commit your API keys to version control.

Risk Controls

AgentPayAPI enforces risk limits cryptographically before any transaction is signed. If a transaction violates a limit, it is blocked at the API level and never broadcast to the network.

• Global Limits: Maximum transaction value, daily volume limits, and allowed networks.
• Per-Contract Limits: Restrict agents to interact only with specific smart contracts (e.g., only Uniswap V3 routers).
• Velocity Limits: Maximum number of transactions per hour/day to prevent runaway loops.

Production note: USD limits use a reference ETH price for enforcement—set conservative caps in the dashboard. If you configure a per-wallet allowlist of contract addresses, POST /api/v1/transact rejects any to address not in that list.

Supported Networks

We currently support 7 networks (5 mainnets and 2 testnets). Use the exact string identifier in the chain parameter when executing transactions.

Webhooks

Receive HTTPS callbacks when a transaction is successfully broadcast to the network. Configure your webhook URL, secret, and active state in the Dashboard (Webhooks section). AgentPayAPI stores one webhook per account.

When we notify you

After a transaction is signed and broadcast (e.g. via POST /api/v1/transact or the legacy transactions API), we enqueue a delivery to your URL if webhooks are enabled. Delivery is asynchronous (fire-and-forget); a slow or failing endpoint does not block the API response.

Request

• Method: POST
• Content-Type: application/json
• Signature header: x-agentpay-signature — hex-encoded HMAC-SHA256 of the raw JSON body, using your webhook secret as the key.
• Timeout: 10 seconds per attempt.

Payload shape

The JSON body always includes event, data, and timestamp (ISO 8601).

{
  "event": "transaction.broadcasted",
  "data": {
    "walletId": "<uuid>",
    "to": "0x...",
    "value": "0.1",
    "network": "base",
    "txHash": "0x..."
  },
  "timestamp": "2026-03-26T12:00:00.000Z"
}

network uses the same identifiers as Supported Networks (e.g. base, sepolia).

Verifying signatures

Recompute HMAC-SHA256 over the exact raw request body bytes with your webhook secret; compare to x-agentpay-signature (hex). Reject requests with a mismatch.

const crypto = require("crypto");

// Use the raw body string exactly as received (before JSON parse), or
// stringify req.body with the same key order AgentPay sent — simplest is
// to verify using raw body middleware (e.g. express.raw) then parse JSON.

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = req.body;
  const signature = req.headers["x-agentpay-signature"];
  const expected = crypto
    .createHmac("sha256", process.env.AGENTPAY_WEBHOOK_SECRET)
    .update(rawBody)
    .digest("hex");

  if (signature !== expected) {
    return res.status(401).send("Invalid signature");
  }

  const payload = JSON.parse(rawBody.toString("utf8"));
  // payload.event === "transaction.broadcasted"
  // payload.data.txHash, ...
  res.status(200).send("OK");
});

URL requirements

For security (SSRF protection), URLs must not use embedded credentials, and in production must use https:. Localhost, private IP literals, and certain internal hosts are rejected. Use a public HTTPS endpoint (or an HTTP tunnel in development only where allowed).

Client Initialization

Initialize the AgentPay client with your API key. You can pass the key directly, or let the SDK automatically pick it up from the AGENTPAY_API_KEY environment variable.

import { AgentPay } from '@agentpay/sdk';// Option 1: Pass API key explicitlyconst client = new AgentPay('sk_live_...');// Option 2: Uses process.env.AGENTPAY_API_KEY automaticallyconst client = new AgentPay();

Execute Transaction

Execute a transaction on-chain. The API will automatically evaluate the transaction against your configured risk limits before signing and broadcasting.

const receipt = await client.execute({ to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e', value: '0.05', chain: 'base', data: '0x' // Optional contract calldata});

Parameters