@lucid/client — API + A2A Hub Client

Overview

• Typed helpers and schemas for the server API.
• Thin A2A hub client to interoperate with registered agents by agentRef.

A2A Hub Client

• Import: import { A2AHubClient } from '@lucid/client'.
• Construct with your API base URL and optional headers or API key.

Using x402-fetch for payments

• Install: x402-fetch
• Example: import { createSigner, wrapFetchWithPayment } from 'x402-fetch'; const signer = await createSigner('base-sepolia', process.env.PRIVATE_KEY!); const paidFetch = wrapFetchWithPayment(fetch, signer); const client = new A2AHubClient('http://localhost:8787', { fetch: paidFetch }); // Headers added by x402-fetch are forwarded by the hub to target agents

Paid client helper

• Import: import { createPaidA2AHubClient } from '@lucid/client'.
• Example: const client = await createPaidA2AHubClient({ hubUrl: 'http://localhost:8787', privateKey: process.env.PRIVATE_KEY!, network: process.env.PAYMENT_NETWORK || process.env.NETWORK || 'base-sepolia', }); // Same API as A2AHubClient await client.sendMessage({ agentRef: 'echo-agent', skillId: 'echo', input: { text: 'hi' } });

Examples

• Get agent card: const client = new A2AHubClient('http://localhost:8787', { apiKey: process.env.API_KEY }); const card = await client.getCard('echo-agent');

• Send a non-streaming task: const task = await client.sendMessage({ agentRef: 'echo-agent', skillId: 'echo', input: { text: 'hello' } }); // task.kind === 'task'; task.status.state in ['completed','failed','unknown']

• Stream a task: const ac = new AbortController(); try { for await (const evt of client.sendMessageStream({ agentRef: 'echo-agent', skillId: 'echo', input: { text: 'stream me' }, signal: ac.signal })) { if (evt.kind === 'task') console.log('task opened', evt.id); else if (evt.kind === 'status-update') console.log('status', evt.status.state, evt.status.message?.parts?.[0]?.text); } } finally { ac.abort(); }

Notes

• skillId is optional if the agent only advertises a single entrypoint.
• Streaming yields a task first, then status-update events until a final update (final: true).
• Errors in the stream are thrown by the iterator; wrap in try/catch.
• Payments (x402): pass your x-402-* headers via the client constructor, e.g. new A2AHubClient(url, { headers: { 'x-402-token': '...', 'x-402-signature': '...' } }). The hub forwards these to the target agent.

Node paid demo

• A runnable script is included at apps/examples/a2a/paid-demo.ts that:
  • Fetches an agent card via the hub
  • Sends an A2A RPC task (non-stream)
  • Invokes and streams via direct hub endpoints with x402 payments (headers auto-managed by x402-fetch)

Run (Bun):

HUB_URL=http://localhost:8787 \
AGENT_REF=echo-agent \
SKILL_ID=echo \
NETWORK=base-sepolia \
PRIVATE_KEY=0x... \
bun run apps/examples/a2a/paid-demo.ts

Notes:

• For paid flows, ensure the target agent is configured with x402 (payee address, network, facilitator).
• The demo prints x-payment-response when present; 402 challenges are handled by x402-fetch when using the direct endpoints.