Documentation

Everything you need to integrate x402-compliant AI-to-AI settlement on Algorand.

Overview

The @algo-wallet/x402-client SDK handles the full x402 payment handshake automatically. Your agent sends a request, gets a 402 bounce with payment terms, and the SDK absorbs it — building the Ed25519 proof and settling the atomic group on-chain. Three lines of code.

Install

bash
npm install @algo-wallet/x402-client algosdk

Quick Start

typescript
import { AlgoAgentClient } from "@algo-wallet/x402-client";

const client = new AlgoAgentClient({
  baseUrl: "https://your-x402-server.vercel.app",
  privateKey: yourAlgorandSecretKey, // 64-byte Uint8Array
});

const result = await client.executeTrade({ senderAddress: "AAAA...7Q" });
console.log(result);
// { success: true, settlement: { txnId: "...", confirmedRound: 12345 } }

402 Handshake Flow

executeTrade()

├─ POST /api/agent-action ← Initial request (no proof)

│   ↳ 402 Payment Required ← Server bounces with pay+json terms

├─ Parse 402 terms ← Extract USDC amount, payTo, asset ID

├─ Build atomic group ← ASA transfer to treasury

├─ Sign groupId ← Ed25519 signature with your key

├─ Retry with X-PAYMENT header injected

│   ↳ 200 SandboxExport ← Unsigned atomic group returned

└─ POST /api/execute ← Forward to settlement pipeline

     ↳ 200 SettlementResult ← On-chain confirmation

API Reference

POST/api/agent-action

Initiates a trade action. Returns 402 with payment terms on first call, then 200 with SandboxExport when X-PAYMENT header is present.

Parameters

senderAddressstringrequiredAlgorand address
amountnumberMicro-USDC amount
destinationChainstringWormhole target (default: "ethereum")
POST/api/execute

Forwards a SandboxExport to the settlement pipeline. Signs and submits the atomic group on-chain.

Parameters

sandboxExportSandboxExportrequiredFrom agent-action 200 response
GET/api/telemetry

Returns real-time protocol metrics and recent audit events for the dashboard.

SDK Methods

new AlgoAgentClient(config)
baseUrlstringRequiredx402 server URL
privateKeyUint8ArrayRequired64-byte Algorand Ed25519 secret key
slippageBipsnumberOptionalSlippage tolerance (default: 50 = 0.5%)
client.executeTrade(params)
senderAddressstringRequiredYour Algorand address
amountnumberOptionalMicro-USDC amount
destinationChainstringOptionalWormhole target (default: "ethereum")
destinationRecipientstringOptionalRecipient on destination chain
client.requestSandboxExport(params)

Performs the 402 handshake only. Returns the SandboxExport for inspection before settlement.

client.settle(response)

Forwards a previously obtained AgentActionResponse to /api/execute.

Types

typescript
import type {
  TradeParams,
  TradeResult,
  SettlementResult,
  SettlementFailure,
  SandboxExport,
  PayJson,
} from "@algo-wallet/x402-client";

Error Handling

typescript
import { X402Error } from "@algo-wallet/x402-client";

try {
  const result = await client.executeTrade({ senderAddress: "AAAA...7Q" });
  if ("success" in result) {
    console.log("Settled:", result.settlement.txnId);
  } else {
    console.error("Pipeline failed at:", result.failedStage, result.detail);
  }
} catch (err) {
  if (err instanceof X402Error) {
    console.error("x402 protocol error:", err.message);
  }
}