Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

14.3 KB
Raw Blame
// agent-payments-sdk
// Copyright (c) 2026 nirholas | x.com/nichxbt | github.com/nirholas
// All rights reserved.
//
// A2A (Agent-to-Agent) x402 client helpers.
//
// Drives the two-leg A2A x402 handshake described at
//   https://github.com/google-agentic-commerce/a2a-x402/blob/main/spec/v0.1/spec.md
//
// Other agents in this workspace import these to call a paid A2A skill on a
// peer agent without re-implementing the JSON-RPC + EIP-3009 signing dance.
//
// Usage:
//   import { payA2A, createPrivateKeySigner } from "@pump-fun/agent-payments-sdk/a2a";
//
//   const signer = await createPrivateKeySigner(process.env.AGENT_PRIVATE_KEY!);
//   const result = await payA2A({
//     endpoint: "https://three.ws/api/agents/a2a-paid",
//     signer,
//     text: "Inspect https://example.com/model.glb",
//   });
//   console.log(result.task.artifacts);

import { privateKeyToAccount } from "viem/accounts";
import type { Address, Hex } from "viem";

export const A2A_X402_EXTENSION_URI =
  "https://github.com/google-a2a/a2a-x402/v0.1";
export const A2A_EXTENSIONS_HEADER = "X-A2A-Extensions";

// ── Errors ────────────────────────────────────────────────────────────────

export class A2AClientError extends Error {
  code: string;
  details?: unknown;
  constructor(code: string, message: string, details?: unknown) {
    super(message);
    this.name = "A2AClientError";
    this.code = code;
    this.details = details;
  }
}

// ── Types ─────────────────────────────────────────────────────────────────

export interface A2ASigner {
  address: Address;
  signAuthorization(args: {
    domain: {
      name: string;
      version: string;
      chainId: number;
      verifyingContract: Address;
    };
    message: {
      from: Address;
      to: Address;
      value: string;
      validAfter: number;
      validBefore: number;
      nonce: Hex;
    };
  }): Promise<Hex>;
}

export interface A2APaymentRequirementsAccept {
  scheme: string;
  network: string;
  amount: string;
  asset: Address;
  payTo: Address;
  maxTimeoutSeconds?: number;
  extra?: {
    name?: string;
    version?: string;
    decimals?: number;
    [key: string]: unknown;
  };
}

export interface A2APaymentRequirements {
  x402Version: number;
  error?: string;
  resource: { url: string; description?: string; mimeType?: string };
  accepts: A2APaymentRequirementsAccept[];
}

export interface A2APaymentPayload {
  x402Version: number;
  scheme: string;
  network: string;
  resource: { url: string; mimeType?: string; description?: string };
  accepted: A2APaymentRequirementsAccept;
  payload: {
    signature: Hex;
    authorization: {
      from: Address;
      to: Address;
      value: string;
      validAfter: string;
      validBefore: string;
      nonce: Hex;
    };
  };
  extensions?: Record<string, unknown>;
}

export interface A2ATaskMessagePart {
  kind: "text" | "data" | "image" | "file";
  text?: string;
  data?: unknown;
  name?: string;
  mimeType?: string;
}

export interface A2ATaskMessage {
  kind: "message";
  role: "agent" | "user";
  messageId?: string;
  taskId?: string;
  parts: A2ATaskMessagePart[];
  metadata?: Record<string, unknown>;
}

export interface A2ATask {
  kind: "task";
  id: string;
  status: { state: string; message?: A2ATaskMessage };
  artifacts?: Array<{
    artifactId?: string;
    name?: string;
    description?: string;
    parts?: A2ATaskMessagePart[];
    mimeType?: string;
    data?: unknown;
  }>;
}

export interface A2APaymentResult {
  task: A2ATask;
  state: string;
  status: string | null;
  receipts: Array<{
    success: boolean;
    transaction?: string;
    network?: string;
    payer?: string | null;
    errorReason?: string;
  }>;
  error: string | null;
  lifecycle: string[] | null;
}

// ── Signers ───────────────────────────────────────────────────────────────

export async function createPrivateKeySigner(privateKey: string): Promise<A2ASigner> {
  if (!privateKey || typeof privateKey !== "string") {
    throw new A2AClientError(
      "invalid_signer",
      "createPrivateKeySigner: hex string required",
    );
  }
  const account = privateKeyToAccount(
    privateKey.startsWith("0x") ? (privateKey as Hex) : (`0x${privateKey}` as Hex),
  );
  return {
    address: account.address,
    signAuthorization: async ({ domain, message }) =>
      account.signTypedData({
        domain,
        types: {
          TransferWithAuthorization: [
            { name: "from", type: "address" },
            { name: "to", type: "address" },
            { name: "value", type: "uint256" },
            { name: "validAfter", type: "uint256" },
            { name: "validBefore", type: "uint256" },
            { name: "nonce", type: "bytes32" },
          ],
        },
        primaryType: "TransferWithAuthorization",
        message: {
          from: message.from,
          to: message.to,
          value: BigInt(message.value),
          validAfter: BigInt(message.validAfter),
          validBefore: BigInt(message.validBefore),
          nonce: message.nonce,
        },
      }),
  };
}

// ── Payload helpers ───────────────────────────────────────────────────────

const CHAIN_ID_BY_NETWORK: Record<string, number> = {
  "eip155:8453": 8453,
  "eip155:84532": 84532,
  "eip155:1": 1,
  "eip155:137": 137,
  "eip155:42161": 42161,
};

function chainIdFor(network: string): number {
  if (CHAIN_ID_BY_NETWORK[network]) return CHAIN_ID_BY_NETWORK[network];
  const m = /^eip155:(\d+)$/.exec(network);
  if (m && m[1]) return Number(m[1]);
  throw new A2AClientError(
    "unsupported_network",
    `a2a-helpers: cannot derive chainId from ${network}`,
  );
}

function randomHex32(): Hex {
  // 32 bytes of randomness as 0x-prefixed hex. crypto.getRandomValues is
  // available in Node 18+ and every modern runtime.
  const bytes = new Uint8Array(32);
  crypto.getRandomValues(bytes);
  let hex = "0x";
  for (const b of bytes) hex += b.toString(16).padStart(2, "0");
  return hex as Hex;
}

export async function buildEvmExactPayload(args: {
  accept: A2APaymentRequirementsAccept;
  signer: A2ASigner;
  resource: { url: string; mimeType?: string; description?: string };
}): Promise<A2APaymentPayload> {
  const { accept, signer, resource } = args;
  if (accept.scheme !== "exact") {
    throw new A2AClientError(
      "unsupported_scheme",
      `a2a-helpers: only exact scheme supported, got ${accept.scheme}`,
    );
  }
  const chainId = chainIdFor(accept.network);
  const validAfter = 0;
  const validBefore = Math.floor(Date.now() / 1000) + (accept.maxTimeoutSeconds || 600);
  const nonce = randomHex32();
  const domain = {
    name: accept.extra?.name || "USD Coin",
    version: accept.extra?.version || "2",
    chainId,
    verifyingContract: accept.asset,
  };
  const message = {
    from: signer.address,
    to: accept.payTo,
    value: accept.amount,
    validAfter,
    validBefore,
    nonce,
  };
  const signature = await signer.signAuthorization({ domain, message });
  return {
    x402Version: 2,
    scheme: "exact",
    network: accept.network,
    resource,
    accepted: accept,
    payload: {
      signature,
      authorization: {
        from: signer.address,
        to: accept.payTo,
        value: accept.amount,
        validAfter: String(validAfter),
        validBefore: String(validBefore),
        nonce,
      },
    },
  };
}

// ── JSON-RPC plumbing ─────────────────────────────────────────────────────

function jsonRpcRequest(message: A2ATaskMessage) {
  const id =
    typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `${Date.now()}-${Math.random()}`;
  return {
    jsonrpc: "2.0" as const,
    id,
    method: "message/send" as const,
    params: { message },
  };
}

async function postJsonRpc(endpoint: string, body: unknown): Promise<A2ATask> {
  const res = await fetch(endpoint, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      accept: "application/json",
      [A2A_EXTENSIONS_HEADER]: A2A_X402_EXTENSION_URI,
    },
    body: JSON.stringify(body),
  });
  const text = await res.text();
  let parsed: { result?: A2ATask; error?: { code: number; message: string; data?: unknown } };
  try {
    parsed = text ? JSON.parse(text) : {};
  } catch (err) {
    throw new A2AClientError(
      "parse_error",
      `non-JSON A2A reply: ${(err as Error).message}`,
      { text },
    );
  }
  if (!res.ok) {
    throw new A2AClientError("transport_error", `HTTP ${res.status}`, {
      status: res.status,
      body: parsed,
    });
  }
  if (parsed.error) {
    throw new A2AClientError(
      "jsonrpc_error",
      parsed.error.message || "JSON-RPC error",
      parsed.error,
    );
  }
  if (!parsed.result || parsed.result.kind !== "task") {
    throw new A2AClientError("invalid_reply", "expected `kind: task` in A2A reply", parsed.result);
  }
  return parsed.result;
}

function readPaymentRequired(task: A2ATask): A2APaymentRequirements | null {
  const meta = task.status?.message?.metadata as Record<string, unknown> | undefined;
  if (!meta || meta["x402.payment.status"] !== "payment-required") return null;
  const required = meta["x402.payment.required"];
  if (
    !required ||
    typeof required !== "object" ||
    !Array.isArray((required as A2APaymentRequirements).accepts)
  ) {
    throw new A2AClientError(
      "malformed_payment_required",
      "task carries payment-required status but no accepts list",
      required,
    );
  }
  return required as A2APaymentRequirements;
}

function readReceiptInfo(task: A2ATask) {
  const meta = (task.status?.message?.metadata || {}) as Record<string, unknown>;
  return {
    status: (meta["x402.payment.status"] as string) || null,
    receipts: Array.isArray(meta["x402.payment.receipts"])
      ? (meta["x402.payment.receipts"] as A2APaymentResult["receipts"])
      : [],
    error: (meta["x402.payment.error"] as string) || null,
    lifecycle: Array.isArray(meta["x402.payment.lifecycle"])
      ? (meta["x402.payment.lifecycle"] as string[])
      : null,
  };
}

const DEFAULT_NETWORK_PREFERENCE = ["eip155:8453", "eip155:84532", "eip155:1"];

function pickAccept(
  accepts: A2APaymentRequirementsAccept[],
  preference?: string[],
): A2APaymentRequirementsAccept {
  const order = preference?.length ? preference : DEFAULT_NETWORK_PREFERENCE;
  for (const net of order) {
    const match = accepts.find((a) => a.network === net && a.scheme === "exact");
    if (match) return match;
  }
  for (const a of accepts) {
    if (a.scheme === "exact" && /^eip155:\d+$/.test(a.network)) return a;
  }
  throw new A2AClientError(
    "no_supported_accept",
    "a2a-helpers: peer offered no supported (scheme=exact, EVM) accept",
    { accepts: accepts.map(({ network, scheme }) => ({ network, scheme })) },
  );
}

// ── Public API ────────────────────────────────────────────────────────────

export async function requestA2AQuote(args: {
  endpoint: string;
  text?: string;
  taskId?: string;
}): Promise<{ task: A2ATask; required: A2APaymentRequirements; taskId: string }> {
  const message: A2ATaskMessage = {
    kind: "message",
    role: "user",
    messageId: typeof crypto.randomUUID === "function" ? crypto.randomUUID() : undefined,
    ...(args.taskId ? { taskId: args.taskId } : {}),
    parts: [{ kind: "text", text: args.text || "Initiate paid skill." }],
  };
  const task = await postJsonRpc(args.endpoint, jsonRpcRequest(message));
  const required = readPaymentRequired(task);
  if (!required) {
    throw new A2AClientError(
      "unexpected_state",
      `expected payment-required, got state ${task.status?.state || "unknown"}`,
      { task },
    );
  }
  return { task, required, taskId: task.id };
}

export async function submitA2APayment(args: {
  endpoint: string;
  taskId: string;
  paymentPayload: A2APaymentPayload;
  text?: string;
}): Promise<A2APaymentResult> {
  const message: A2ATaskMessage = {
    kind: "message",
    role: "user",
    messageId: typeof crypto.randomUUID === "function" ? crypto.randomUUID() : undefined,
    taskId: args.taskId,
    parts: [{ kind: "text", text: args.text || "Here is the payment authorization." }],
    metadata: {
      "x402.payment.status": "payment-submitted",
      "x402.payment.payload": args.paymentPayload,
    },
  };
  const task = await postJsonRpc(args.endpoint, jsonRpcRequest(message));
  const receipt = readReceiptInfo(task);
  return {
    task,
    state: task.status?.state || "unknown",
    ...receipt,
  };
}

export interface PayA2AOptions {
  endpoint: string;
  signer: A2ASigner;
  text?: string;
  networkPreference?: string[];
  onQuote?: (args: {
    task: A2ATask;
    required: A2APaymentRequirements;
    taskId: string;
  }) => void | Promise<void>;
}

export async function payA2A(opts: PayA2AOptions): Promise<A2APaymentResult> {
  if (!opts.endpoint) {
    throw new A2AClientError("invalid_args", "payA2A: endpoint required");
  }
  if (!opts.signer || typeof opts.signer.signAuthorization !== "function") {
    throw new A2AClientError(
      "invalid_signer",
      "payA2A: signer with signAuthorization() required",
    );
  }

  const quote = await requestA2AQuote({ endpoint: opts.endpoint, text: opts.text });
  if (opts.onQuote) await opts.onQuote(quote);

  const accept = pickAccept(quote.required.accepts, opts.networkPreference);
  const resource = quote.required.resource || {
    url: opts.endpoint,
    mimeType: "application/json",
  };
  const paymentPayload = await buildEvmExactPayload({ accept, signer: opts.signer, resource });

  const result = await submitA2APayment({
    endpoint: opts.endpoint,
    taskId: quote.taskId,
    paymentPayload,
  });

  if (result.state !== "completed") {
    throw new A2AClientError(
      result.error || "payment_failed",
      result.receipts[0]?.errorReason || `A2A task ended in state ${result.state}`,
      result,
    );
  }
  return result;
}