Node / TypeScript Quickstart

AiFinPay is payment infrastructure for AI agents — the Stripe for autonomous software. The Node SDK lets an agent hold its own non-custodial wallet, settle an HTTP 402 challenge on-chain, and get the gated response back in a single call. No KYC, no API key, no custodian holds your funds.

AiFinPay is token-free. Agents pay in real assets — USDC, USDT, SOL, MATIC — settled on Solana and Polygon mainnet. There is no AiFinPay token to buy or hold. mSECCO is a non-transferable internal accounting unit, not a tradable asset.

Install

npm install @aifinpay/agent
# or: pnpm add @aifinpay/agent
# or: yarn add @aifinpay/agent

The package ships as ESM ("type": "module"), so the top-level await used in the snippets below works directly in a .mjs / .ts module.

Your first paid call

The fastest path: generate a fresh agent, fund it, and call agent.pay(url). The Ed25519 / EVM keypair is generated locally with tweetnacl and never leaves your process — the SDK only sends a one-time signature to authenticate.

Generate an agent and print its address

import { Agent } from "@aifinpay/agent";

// Fresh keypair, generated locally. Persist `secretB58` to reuse this identity.
const agent = Agent.new();
console.log("Fund this address:", agent.address);
console.log("Save this secret:", agent.secretB58); // store securely!

Fund the address

Send a few cents of the appropriate asset to the printed address. You can poll until funds arrive:

// Block until the wallet holds at least $0.01 on-chain
await agent.waitForFunding({ minUsdCents: 1 });

Pay and get the response

const res = await agent.pay(
  "https://bridge.aifinpay.io/io-net/chat/completions",
  {
    body: {
      model: "meta-llama/Llama-3.3-70B-Instruct",
      messages: [{ role: "user", content: "Hello" }],
    },
  },
);

const data = await res.json();
console.log(data.choices[0].message.content);

agent.pay() handles the whole 402 dance for you: it reads the challenge, settles the payment on-chain, retries with the proof, and returns the upstream response.

The capability layer: `AiFinPayAgent`

agent.pay(url) is perfect when you already know the endpoint. When you’d rather ask for a capability (“search this”, “run this inference”) and let AiFinPay route to the best live provider, use the unified AiFinPayAgent. It manages both a Solana and an EVM identity and settles each call atomically on-chain.

import { AiFinPayAgent } from "@aifinpay/agent";

// AiFinPayAgent.new() is async — it provisions both keypairs.
const agent = await AiFinPayAgent.new();

console.log("Solana address:", agent.solanaAddress);
console.log("EVM address:   ", agent.evmAddress);

The unified call() / capability flow settles per-call payments on Polygon mainnet by default, so fund the EVM address (agent.evmAddress) with a few cents of MATIC. Use agent.balance() to confirm funds landed.

Discover providers

discover() browses the live provider catalog. Filter by category ("search", "inference", "image", "speech") and/or free-text q. Each entry carries live connectivity so you can rank client-side too.

const providers = await agent.discover({ category: "search", limit: 5 });

for (const p of providers) {
  console.log(p.slug, p.name, p.price_usd, p.status, `${p.latency_ms}ms`);
  // e.g. "exa  Exa Search  0.005  live  120ms"
}

Each result is a DiscoveredProvider: slug, name, price_usd, availability ("available" | "recruiting"), status ("live" | "down" | "unknown"), latency_ms, and an optional transparent score.

Pick the single best provider

pickProvider() asks the gateway for the best available provider in a category, ranked by price, latency, liveness, and on-chain trust. Cap the candidate set with maxPriceUsd.

const best = await agent.pickProvider("inference", { maxPriceUsd: 0.05 });
console.log("Routing to:", best.name, "@", best.price_usd, "USD/call");

It throws ProviderUnknownError when nothing payable matches.

One-line web search

webSearch() is the highest-level call: it picks the best search provider, pays it, and returns the response. It resolves to null only if a budget cap is hit in "skip" mode (see below).

const res = await agent.webSearch("latest Solana TPS benchmarks");
if (res) {
  const data = await res.json();
  console.log(data);
}

The sibling capability methods follow the same shape:

await agent.webSearch("who founded CoinSecurities?");

await agent.infer({
  model: "meta-llama/Llama-3.3-70B-Instruct",
  messages: [{ role: "user", content: "Summarize x402 in one line." }],
});

await agent.image("a neon terminal paying an API, vaporwave");

await agent.voice("Payment settled on-chain.");

Call a provider by name

If you already know which provider you want, skip routing and call it directly. call() resolves the provider, picks a chain, settles on-chain, and retries with payment proof.

const res = await agent.call({
  provider: "io-net",
  body: {
    model: "meta-llama/Llama-3.3-70B-Instruct",
    messages: [{ role: "user", content: "Hello" }],
  },
});

if (res) {
  const data = await res.json();
  console.log(data.choices[0].message.content);
}

call() accepts { provider, body, cost?, chain?, bridgeUrl?, method?, timeoutMs?, signal? } and returns Promise<Response | null>.

Budget caps

Cap per-call and daily spend at construction time, or update later with setBudget(). With on_limit_exceeded: "skip", a call that would breach a cap resolves to null instead of paying — useful in loops where you’d rather drop a task than overspend.

const agent = await AiFinPayAgent.new({
  budgetCaps: {
    daily_usd: 5.0,
    per_call_usd: 0.10,
    on_limit_exceeded: "skip", // default is "throw" (BudgetCapExceededError)
  },
});

// ...later
agent.setBudget({ daily_usd: 20.0 });
console.log("Spent in last 24h:", agent.getSpend24h(), "USD");

Check balances across chains

balance() returns a USD-normalised snapshot across both chains, plus rolling 24h spend and the active caps.

const snap = await agent.balance();
console.log("Total:", snap.agent_balance_usd, "USD");
console.log("Polygon:", snap.chains.polygon.matic, "MATIC,", snap.chains.polygon.usdc, "USDC");
console.log("Solana: ", snap.chains.solana.sol, "SOL,", snap.chains.solana.usdc, "USDC");
console.log("24h spend:", snap.spend_24h_usd, "USD");

The snapshot also reports msecco_balance per chain. mSECCO are non-transferable usage credits earned by paying agents — they are not tradable and cannot be withdrawn.

Loading an existing keypair

To reuse an agent identity across runs, load it instead of generating a new one.

Agent (simple)
AiFinPayAgent (unified)

import { Agent } from "@aifinpay/agent";

// From a solana-keygen JSON file (Node only)
const a1 = await Agent.fromKeypairFile("./agent-wallet.json");

// From a base58 secret string (also works in the browser)
const a2 = Agent.fromSecretB58("3RvZm7Gw...");

import { AiFinPayAgent } from "@aifinpay/agent";

// Derives the matching EVM address deterministically from the Solana secret.
const agent = await AiFinPayAgent.fromSolanaSecret("3RvZm7Gw...");

// Or derive both chains from a single 32-byte hex seed (one backup, two chains)
const seeded = await AiFinPayAgent.fromSeed("0xabc123...");

How a payment settles

You see one function call. Under the hood, for every paid request the SDK:

Sends the request unauthenticated → the bridge replies with HTTP 402 and a JSON challenge listing chain, asset, recipient, amount and nonce.
Settles on-chain — either an Ed25519-signed Solana challenge or a Polygon B2BSplitter.payMatic() transaction, depending on what the server accepts. The split is atomic (merchant / treasury / IP-creator) and no custodian ever holds the funds.
Retries the original request with the payment proof header (e.g. x-tx-hash + x-order-id on Polygon, or x-solana-tx on Solana).
Returns the upstream response once the bridge has verified settlement on-chain.

All transactions are public on Solana and Polygon mainnet.

Next steps

x402 discovery doc

The machine-readable discovery document agents read to find payable endpoints.

GitHub Issues

Questions, bugs, and feature requests for the SDK.

Get started

Pay for services

Charge for your API

Reference

Node / TypeScript Quickstart

Install

Your first paid call

The capability layer: `AiFinPayAgent`

Discover providers

Pick the single best provider

One-line web search

Call a provider by name

Budget caps

Check balances across chains

Loading an existing keypair

How a payment settles

Next steps

x402 discovery doc

GitHub Issues

​Install

​Your first paid call

​The capability layer: AiFinPayAgent

​Discover providers

​Pick the single best provider

​One-line web search

​Call a provider by name

​Budget caps

​Check balances across chains

​Loading an existing keypair

​How a payment settles

​Next steps

x402 discovery doc

GitHub Issues

Install

Your first paid call

The capability layer: `AiFinPayAgent`

Discover providers

Pick the single best provider

One-line web search

Call a provider by name

Budget caps

Check balances across chains

Loading an existing keypair

How a payment settles

Next steps