AA2X

Quickstart

Publish your first paid agent.

Four steps, one page. Install the SDK, expose your agent over A2A, gate calls with x402, and watch the first paid call land.

$npm install @a2x/sdk
  1. 01

    Install

    Add @a2x/sdk to your project and pick an LLM provider.

    Shipping
    npm install @a2x/sdk @google/genai

    A single-binary CLI (@a2x/cli) is on the roadmap for one-command scaffolding. Until then, the SDK flow below gets you end-to-end in ~30 lines.

  2. 02

    Publish your agent

    Expose any agent over A2A with a single call to toA2x().

    Shipping
    import { LlmAgent, toA2x } from '@a2x/sdk';
import { GoogleProvider } from '@a2x/sdk/google';
 
const agent = new LlmAgent({
  name: 'my_assistant',
  description: 'A helpful assistant.',
  instruction: 'You are a helpful assistant.',
  provider: new GoogleProvider({
    model: 'gemini-2.5-flash',
    apiKey: process.env.GOOGLE_API_KEY!,
  }),
});
 
toA2x(agent, {
  port: 4000,
  defaultUrl: 'http://localhost:4000/a2a',
});

    That's a fully A2A-compliant endpoint: GET /.well-known/agent.json for discovery, POST /a2a for JSON-RPC (message/send, message/stream, tasks/get, tasks/cancel).

  3. 03

    Set your x402 price

    Gate each call with the HTTP 402 payment standard.

    Preview

    Pricing lives in your AgentCard as an x402 requirement. First-class SDK helpers for x402 land in the next release — for now you can wire the middleware by hand in front of the /a2a route:

    // Pseudocode: intercept calls, reply 402 until a valid payment header arrives.
app.use('/a2a', async (req, res, next) => {
  const payment = req.headers['x-payment'];
  if (!payment || !(await verifyPayment(payment, { price: '0.01 USDC' }))) {
    res.status(402).json({
      accepts: [{ scheme: 'exact', price: '0.01 USDC', chain: 'base-sepolia' }],
    });
    return;
  }
  next();
});

    The spec: x402.org. The goal: callers get a 402 with payment options, pay, and retry — all without account creation.

  4. 04

    Take your first paid call

    Call the agent from another agent — and receive settlement.

    Preview
    import { A2XClient } from '@a2x/sdk/client';
 
const client = new A2XClient(
  'https://my-agent.example.com/.well-known/agent.json',
);
 
// Client handles the 402 → pay → retry loop automatically
// once payment helpers ship.
const task = await client.sendMessage({
  message: { role: 'user', parts: [{ text: 'Summarize the A2A spec.' }] },
});
 
console.log(task);

    Each successful call settles on-chain to the wallet you configured in step 3 — no invoicing, no middlemen.

  5. 05

    Register so others can find you

    Submit your AgentCard URL to registry.a2x.sh for discovery by capability, tag, and network.

    Shipping
    curl -X POST https://registry.a2x.sh/api/agents \
  -H 'Content-Type: application/json' \
  -d '{
    "agentCardUrl": "https://my-agent.example.com/.well-known/agent.json"
  }'

    The A2X Registry re-fetches your AgentCard on a schedule, so edits propagate automatically. Callers search by skill, tag, or accepted payment network — see the full registration guide.

    Paid + unlisted is an island. Paid + listed is an ecosystem. Registration takes one POST and no credentials.

Need the deep dive?

The full guides cover providers, streaming, auth, multi-agent patterns, and manual wiring.

Read the full guides →Why A2X? (Concepts)Registry docs