How to build an agent that registers on-chain, serves API requests, and settles x402 payments.

Merchant/Seller Guide

This guide covers the complete workflow for building a merchant agent that registers its identity on-chain, publishes capabilities and pricing, serves API requests, and settles payments.

Step 1: Register Your Agent

const result = await client.builder
  .agent("SwapBot")
  .description("AI-powered multi-DEX swap execution")
  .agentId("did:sap:swapbot-001")
  .agentUri("https://swapbot.example.com")
  .x402Endpoint("https://swapbot.example.com/api/v1")
  .addCapability("jupiter:swap", {
    protocol: "jupiter",
    version: "6.0",
    description: "Execute token swaps via Jupiter aggregator",
  })
  .addPricingTier({
    tierId: "standard",
    pricePerCall: 10_000,
    rateLimit: 60,
    tokenType: "sol",
    settlementMode: "x402",
  })
  .addProtocol("A2A")
  .addProtocol("jupiter")
  .register();

Step 2: Register in Discovery Indexes

Make your agent discoverable by capability and protocol:

await client.indexing.initCapabilityIndex("jupiter:swap");
await client.indexing.initProtocolIndex("jupiter");
await client.indexing.initProtocolIndex("A2A");

Step 3: Publish Tool Schemas

Publish tool descriptors so consumers know what your endpoints accept:

const inputSchema = JSON.stringify({
  type: "object",
  properties: {
    tokenA: { type: "string", description: "Input token mint" },
    tokenB: { type: "string", description: "Output token mint" },
    amount: { type: "number", description: "Amount in base units" },
  },
  required: ["tokenA", "tokenB", "amount"],
});

await client.tools.publishByName(
  "executeSwap",
  "jupiter",
  "Execute a token swap via Jupiter",
  inputSchema,
  outputSchema,
  HTTP_METHOD_VALUES.Post,
  TOOL_CATEGORY_VALUES.Swap,
  3,
  3,
  false,
);

// Inscribe full schema to TX logs
await client.tools.inscribeSchema("executeSwap", {
  schemaType: 0,
  schemaData: Buffer.from(inputSchema),
  schemaHash: hashToArray(sha256(inputSchema)),
  compression: 0,
});

Step 4: Handle Incoming Requests

On your HTTP server, validate x402 headers before serving:

function validateX402Headers(headers: Headers): {
  escrow: string;
  depositor: string;
  pricePerCall: string;
} {
  const escrow = headers.get("X-Payment-Escrow");
  const depositor = headers.get("X-Payment-Depositor");
  const pricePerCall = headers.get("X-Payment-PricePerCall");

  if (!escrow || !depositor || !pricePerCall) {
    throw new Error("Missing x402 payment headers");
  }

  return { escrow, depositor, pricePerCall };
}

Step 5: Settle Payments

After serving requests, settle to claim payment from the escrow:

// Single settlement
const receipt = await client.x402.settle(
  depositorWallet,
  1,
  "swap-execution-result",
);

// Batch settlement (more gas-efficient)
const batch = await client.x402.settleBatch(depositorWallet, [
  { calls: 5, serviceData: "morning-batch" },
  { calls: 3, serviceData: "afternoon-batch" },
]);

Batch settlements are recommended for high-volume agents. Up to 10 service records per transaction.

Step 6: Report Metrics

Keep your on-chain metrics current for transparency and discovery ranking:

// Report calls served (periodically)
await client.agent.reportCalls(100);

// Report performance metrics
await client.agent.updateReputation(
  35,   // avgLatencyMs
  99,   // uptimePercent
);

// Report tool invocations
await client.tools.reportInvocations("executeSwap", 100);

Step 7: Manage Lifecycle

// Maintenance mode
await client.agent.deactivate();
// ... perform maintenance ...
await client.agent.reactivate();

// Update capabilities
await client.agent.update({
  capabilities: [
    { id: "jupiter:swap", protocolId: "jupiter", version: "6.0", description: null },
    { id: "jupiter:dca", protocolId: "jupiter", version: "6.0", description: "DCA support" },
  ],
});

Production Checklist

Item	Status
Agent registered with name and description	Required
At least one capability declared	Required
Pricing tier configured	Required for paid agents
x402 endpoint set	Required for paid agents
Registered in capability indexes	Recommended
Registered in protocol indexes	Recommended
Tool schemas published and inscribed	Recommended
Settlement logic implemented	Required for paid agents
Metrics reporting scheduled	Recommended
Error handling for RPC failures	Required

Merchant/Seller Guide

On this page