@blockrun/nano-client
Advanced tools
TypeScript client for blockrun-nano: Circle Gateway batched USDC payments → BlockRun's full AI model catalog across Polygon, Arbitrum, Optimism, Unichain.
TypeScript SDK for nano.blockrun.ai — pay-per-request access to 80+ AI models (GPT-5.x, Claude 4.x, Gemini 3.x, DeepSeek, Grok, NVIDIA free-tier, GLM, MiniMax, Moonshot…) plus image / video / music / search / X-Twitter intelligence / Pyth-backed market data — all settled with gas-free batched USDC via Circle Gateway. No API keys required; your wallet signature is your authentication. Built for AI agents that need to operate autonomously across Polygon / Arbitrum / Optimism / Unichain mainnet.
Sister SDKs: blockrun-llm (Python, Base / Solana) · this package = mirror for Circle Gateway batched payments on multi-chain EVM.
Native x402 (e.g. blockrun.ai on Base) | nano.blockrun.ai via Circle Gateway | |
|---|---|---|
| Buyer chain options | Base only | Polygon / Arbitrum / Optimism / Unichain |
| First call setup | Have USDC + ETH on Base | Deposit once into Circle Gateway (one tx) |
| Per-call gas (buyer) | Yes (~$0.01–0.05) | Zero (off-chain EIP-712 signature) |
| Settlement | Synchronous on-chain | Batched ~every 15 min on Polygon |
| Best for | One-off calls | High-frequency AI agents, long-running sessions |
All 10 mainnet chains Circle Gateway supports today (Base excluded by design):
| Chain | SupportedChainName | Chain ID | Native gas |
|---|---|---|---|
| Polygon | polygon | 137 | POL |
| Arbitrum | arbitrum | 42161 | ETH |
| OP Mainnet | optimism | 10 | ETH |
| Unichain | unichain | 130 | ETH |
| Avalanche C-Chain | avalanche | 43114 | AVAX |
| Sonic | sonic | 146 | S |
| Sei EVM | sei | 1329 | SEI |
| WorldChain | worldChain | 480 | ETH |
| HyperEVM | hyperEvm | 999 | HYPE |
| Ethereum | ethereum | 1 | ETH |
Base is intentionally not in nano — buyers on Base should use
blockrun.ai(native x402, no Gateway deposit step required).
npm install @blockrun/nano-client
# or
pnpm add @blockrun/nano-client
import { NanoClient } from "@blockrun/nano-client";
const client = new NanoClient({
chain: "polygon",
privateKey: process.env.PRIVATE_KEY as `0x${string}`,
});
// One-time: move USDC from your wallet into Circle Gateway escrow
await client.deposit("5"); // $5 covers ~5,000 calls @ $0.001
// From here, every call is offchain EIP-712 signature → zero gas
const r = await client.chat({
model: "openai/gpt-4o-mini",
messages: [{ role: "user", content: "Hello!" }],
});
console.log(r.data.choices[0].message.content);
console.log(r.payment.formattedAmount); // "$0.001000"
For an even-shorter shape:
const reply = await client.ask("openai/gpt-4o-mini", "What is 2+2?");
console.log(reply); // "4"
const client = new NanoClient({
privateKey: "0x...", // required (Hex)
chain: "polygon", // required
baseUrl: "https://nano.blockrun.ai", // default
rpcUrl: "https://polygon-mainnet.g.alchemy.com/v2/KEY", // optional override
maxRetries: 2, // default
});
If rpcUrl is omitted, the SDK uses a vetted public RPC per chain from
RECOMMENDED_RPC_URLS (Polygon → 1rpc.io, Arb/Op → llamarpc, Unichain →
drpc). Override for production.
While DNS for nano.blockrun.ai settles, point at the Cloud Run URL:
import { NanoClient, NANO_MAINNET_DIRECT_URL } from "@blockrun/nano-client";
const client = new NanoClient({ chain: "polygon", privateKey, baseUrl: NANO_MAINNET_DIRECT_URL });
const r = await client.chat({
model: "anthropic/claude-haiku-4.5",
messages: [
{ role: "system", content: "You answer in one sentence." },
{ role: "user", content: "Explain MEV." },
],
max_tokens: 200,
});
ask(model, prompt)const reply = await client.ask("openai/gpt-4o-mini", "List 3 EVM rollups");
Let nano pick the cheapest capable model based on a 14-dimension classifier:
const r = await client.smartChat({ prompt: "What is 2+2?" });
console.log(r.data.model); // "moonshot/kimi-k2.5"
const hard = await client.smartChat({
prompt: "Prove the Riemann hypothesis step by step",
routing_profile: "premium",
});
console.log(hard.data.model); // "openai/gpt-5.4"
routing_profile | Behaviour |
|---|---|
"free" | NVIDIA free-tier models only (zero cost) |
"eco" | Cheapest capable model per tier (DeepSeek, NVIDIA) |
"auto" (default) | Best balance of cost / quality |
"premium" | Top-tier (OpenAI, Anthropic) |
const r = await client.images.generate({
model: "openai/dall-e-3",
prompt: "A cat coding TypeScript at sunset, isometric voxel art",
size: "1024x1024",
});
console.log(r.data); // OpenAI-compatible response
Image-to-image edit:
const r = await client.images.edit({
model: "google/nano-banana",
prompt: "Make the sky purple",
image: "data:image/png;base64,…",
});
const job = await client.videos.generate({
model: "minimax/video-01",
prompt: "A red apple slowly rotating on a wooden table",
duration: 6,
});
const status = await client.videos.status(job.data.id); // poll until ready
const m = await client.music.generate({
prompt: "Lo-fi hip hop, soft piano, rainy night",
duration: 30,
});
const r = await client.search({ query: "latest Solana TVL changes this week" });
Powered by AttentionVC. All methods return { data, payment } — typed
generic so you can pass your own response shape.
const profile = await client.x.userInfo("vitalikbuterin");
const followers = await client.x.followers("vitalikbuterin", { cursor: "..." });
const search = await client.x.search("blockrun OR x402", { query_type: "Latest" });
const trending = await client.x.trending();
const tweet = await client.x.tweetLookup("1234567890123456789");
const thread = await client.x.tweetThread("1234567890123456789");
const mentions = await client.x.userMentions("vitalikbuterin");
const articles = await client.x.articlesRising();
Full method list:
| Method | Notes |
|---|---|
client.x.userLookup(usernames) | Profile lookup, single or batch |
client.x.userInfo(username) | Single profile + intel layer |
client.x.followers(username, {cursor?}) | $0.05/page (~200 accounts) |
client.x.followings(username, {cursor?}) | |
client.x.verifiedFollowers(username, {cursor?}) | |
client.x.userTweets(username, {cursor?, limit?}) | |
client.x.userMentions(username, {cursor?, limit?}) | |
client.x.tweetLookup(tweetIds) | Single or batch |
client.x.tweetReplies(tweetId, {cursor?}) | |
client.x.tweetThread(tweetId, {cursor?}) | |
client.x.search(query, {query_type?, cursor?}) | $0.032/page |
client.x.trending() | |
client.x.articlesRising() |
const px = await client.price.price("BTC/USD");
const hist = await client.price.history("ETH/USD", { range: "7d", resolution: "1h" });
const market = await client.price.pm("polymarket", { id: "..." });
client.address; // 0x... derived from privateKey
await client.getBalances(); // wallet + Gateway, on configured chain
await client.deposit("5"); // wallet → Circle Gateway escrow
await client.withdraw("2"); // Gateway → wallet (instant, same chain)
await client.withdraw("2", { chain: "base" }); // Cross-chain via CCTP (~13 min)
When a payment intent reaches Completed, funds land in the seller's
Circle Gateway available balance — not directly in their wallet. The
seller mints to their wallet on whichever chain they want.
Query a seller's Gateway balance — read-only, no private key:
import { querySellerGatewayBalance } from "@blockrun/nano-client";
const b = await querySellerGatewayBalance(
"0xe9030014F5DAe217d0A152f02A043567b16c1aBf", // seller payTo
"polygon",
);
console.log(b.available); // "0.057000"
To mint to wallet (seller-side, requires seller's private key):
const seller = new NanoClient({ chain: "polygon", privateKey: SELLER_KEY });
await seller.withdraw("5"); // → wallet on Polygon
await seller.withdraw("5", { chain: "base" }); // → wallet on Base via CCTP
Every paid call returns payment.transaction — Circle's nanopayment intent UUID.
const r = await client.chat({ ... });
const status = await client.getPaymentStatus(r.payment.transaction);
// → { status: "settled", settledAt: "2026-04-27T23:06:08.267Z" }
// Or block until terminal state:
const final = await client.waitForSettlement(r.payment.transaction, {
timeoutMs: 5 * 60_000,
pollIntervalMs: 10_000,
});
Status flow (per Circle's docs):
| Status | Meaning |
|---|---|
Received | Verified, queued for next batch |
Batched | On-chain batching in progress |
Confirmed | Batch tx submitted on-chain |
Completed | Batch finalised → seller's Circle Gateway balance increased |
Every paid call increments an in-process counter:
const s = client.getSpending();
console.log(`Spent $${s.total_usd.toFixed(4)} across ${s.calls} calls`);
console.log(s.by_endpoint); // { "/v1/chat": {...}, "/v1/x/users": {...} }
client.resetSpending(); // reset for the next session
For endpoints not covered by typed helpers:
const r = await client.call("/api/v1/audio/generations", {
method: "POST",
body: { model: "openai/tts-1", voice: "alloy", input: "Hello" },
});
git clone https://github.com/BlockRunAI/blockrun-nano-client
cd blockrun-nano-client
pnpm install
# 1) Generate fresh test wallet
pnpm exec tsx examples/print-address.ts
# → prints CLIENT_PRIVATE_KEY=0x... and address
# 2) Fund that address on Polygon: 0.5 USDC + 0.05 POL
# 3) Run e2e
CLIENT_PRIVATE_KEY=0x... pnpm exec tsx examples/e2e-test.ts
GatewayWallet contract on chosen chain402 Payment Required with a multi-chain accepts arrayTransferWithAuthorization against GatewayWalletwithdraw()s to wallet (instant, any Gateway-supported chain)Your private key never leaves your machine. The SDK signs locally, only the signature is sent.
.envawait client.getBalances() and alert when gateway.available drops below your thresholdmaxRetries: 2 with exponential backoff handles transient 5xx; bump for high-volume agentsclient.getBalances() per chain over reading the chain yourselfBUYER-GUIDE.mdBlockRunAI/blockrun-nano@circle-fin/x402-batching (Circle)blockrun-llmApache-2.0
FAQs
TypeScript client for blockrun-nano: Circle Gateway batched USDC payments → BlockRun's full AI model catalog across Polygon, Arbitrum, Optimism, Unichain.
The npm package @blockrun/nano-client receives a total of 4 weekly downloads. As such, @blockrun/nano-client popularity was classified as not popular.
We found that @blockrun/nano-client demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Company News
Socket is joining the OpenJS Security Stewardship Program to fund Node.js vulnerability research, maintainer remediation, and security releases.
Security News
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.