TypeScript, CLI, MCP & HTTP examples

Before you run a client example

Follow installation, then complete human CLI setup and unlock. Choose a dedicated funded wallet and a policy that allows the model. Paid SDK and CLI calls spend USDC; the HTTP example below only inspects the unpaid challenge.

The TypeScript SDK, CLI, and MCP server are public npm alphas. The Python SDK remains a source-only bounded subprocess bridge to the matching CLI; it has no independent wallet or signer.

For a task-first request and response guide, including images and both speech directions, use Agent task recipes. For third-party wallet and discovery status, use Wallet and agent compatibility.

Set REQUEST_ID to a stable application job identifier before a paid example. Save it privately with the exact body. Do not create a different key because the original call timed out.

TypeScript

Public npm alpha · requires human setup and an unlocked Buyer Runtime.

npm install @agenticfi/onchain-router@alpha

import { OnchainRouterBuyer } from '@agenticfi/onchain-router';

const requestKey = process.env.REQUEST_ID;
if (!requestKey) throw new Error('Set a persisted REQUEST_ID');
const buyer = await OnchainRouterBuyer.connect();
try {
  const result = await buyer.chat({
    "model": "gemini-3.6-flash",
    "messages": [
      {
        "role": "user",
        "content": "Explain x402 in one sentence."
      }
    ],
    "max_tokens": 128,
    "stream": false
  }, requestKey);
  if (!result.ok) throw new Error(`${result.outcome}: ${result.message}`);
  console.log(result.body);
  console.log(result.receipt.id, result.payment.actualAtomic);
} finally {
  buyer.close();
}

CLI

Public npm alpha · setup, unlock, and policy changes stay human-only.

npm install --global @agenticfi/onchain-router-cli@alpha
onchain-router setup
onchain-router policy show
onchain-router unlock
onchain-router models

MCP

Public npm alpha · prints a local stdio configuration without exposing wallet secrets.

npm install --global @agenticfi/onchain-router-mcp@alpha
onchain-router-mcp --print-config

HTTP

Public API · this plain request inspects the unpaid challenge and does not sign or spend USDC.

request_key="$(node -p 'require("node:crypto").randomUUID()')"
curl -i https://onchainrouter.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -H "x-idempotency-key: $request_key" \
  --data '{"model":"gemini-3.6-flash","messages":[{"role":"user","content":"Explain x402 in one sentence."}],"max_tokens":128,"stream":false}'

Read the result and recover

TypeScript returns a discriminated result: ok, outcome, idempotencyKey, and either a result body, payment and verified receipt, or a safe retry directive.

ProviderOutcomeUnknown and SettlementOutcomeUnknown need human review. A retry directive permitting the same key requires the identical request. Do not wrap paid calls in a general-purpose retry loop.

The examples do not print prompts, completions, signatures, receipt capabilities, or media URLs into diagnostics. Handle output inside your application.

Other capabilities

The same buyer exposes messages, images, speech, and transcriptions. Use each capability's documented request shape.

• Text formats: OpenAI Chat Completions or Anthropic Messages.
• Images: hosted URL or Base64 delivery; hosted URL expires after seven days.
• Speech: hosted MP3 JSON, not an OpenAI binary audio response.
• Transcription: bounded MP3 and explicit retained-provider consent.

Do not implement EIP-712, Permit2, payment signing, or settlement in application code. Buyer Runtime uses official x402 primitives.