cabalspy-x402 — pay-per-call KOL data for AI agents
x402 client for the CabalSpy KOL API. An AI agent pays in USDC per request and gets labeled wallet data on Solana, Base, BNB Chain, Ethereum and Robinhood Chain — no account, no signup, no API key. The wallet is the credential.
npm install cabalspy-x402
Quick start
import { createClient } from 'cabalspy-x402';
const cabalspy = createClient({
signer, // Solana signer
evmSigner, // Base, Polygon, Arbitrum — either or both
maxSpendTotal: '$5.00', // hard cap for this process
});
const wallet = await cabalspy.wallets.lookup('As7HjL7dzzvbRbaD3WCun47robib2kmAKRXMvjHkSMB5');
console.log(wallet.name, wallet.type); // Otta kol
console.log(cabalspy.x402.summary());
// { calls: 1, spentUsd: 0.01, remainingUsd: 4.99 }
The returned object is a full cabalspy client: every endpoint, every type, every error class. Only the payment differs.
Spend limits are on by default
A funded wallet handed to an autonomous agent is a standing authorisation to spend. An agent in a retry loop against a paid endpoint will drain it, and the generic x402 client libraries do not cap this.
So both limits are on unless you turn them off:
| Option | Default | Effect |
|---|
maxSpendPerCall | $0.10 | refuses any single call priced above it |
maxSpendTotal | $10.00 | refuses further calls once reached |
The price is read from the 402 response (the x402 v2 PAYMENT-REQUIRED header, or a v1 body) and checked before the wallet signs anything. When several networks are offered, the highest price counts. A server asking for more than expected is refused without spending a cent, and so is one whose price cannot be read at all (err.kind === 'unpriced').
try {
await cabalspy.signals.list({ blockchain: 'solana', type: 'kol', mode: 'cluster' });
} catch (err) {
if (err instanceof SpendLimitError) {
console.log(err.kind, err.spentUsd, err.limitUsd); // 'total' 9.99 10
}
}
Pass maxSpendTotal: Infinity to disable the cap — deliberately, not by accident. An unreadable price is only accepted when both limits are Infinity.
Which chains you can pay on
CabalSpy accepts payment on Solana, Base, Polygon and Arbitrum, and offers all of
them in the same response. Register whichever you hold USDC on:
createClient({ signer }) // Solana only
createClient({ evmSigner }) // Base, Polygon, Arbitrum
createClient({ signer, evmSigner }) // all four, recommended
createClient({ signer, networks: ['solana'] }) // restrict deliberately
Registering more than one is worth it. The server offers every chain at once, and a
client that can only pay on one is turned away whenever that chain has a problem.
The payment chain has nothing to do with the data: a question about a Base wallet can
be paid for in Solana USDC.
Testnet
api.cabalspy.xyz takes mainnet payments only, so a client restricted to
solana-devnet finds no matching offer there. The option exists for testing
createPaymentFetch against your own x402 endpoint:
const { fetch: pay } = createPaymentFetch({ signer, networks: ['solana-devnet'] });
Against CabalSpy, start with a small maxSpendTotal instead — at $0.01 a call,
'$0.10' buys ten requests.
Just the fetch
For any other x402 endpoint, or to wire payments into your own HTTP layer:
import { createPaymentFetch } from 'cabalspy-x402';
const { fetch: pay, tracker } = createPaymentFetch({ signer, maxSpendTotal: '$1.00' });
const res = await pay('https://api.cabalspy.xyz/v1/signals?blockchain=solana&type=kol');
Your own ledger
Every settled payment is reported, so you can record it alongside whatever else your agent does:
createClient({
signer,
onPayment: (p) => log.info({ tx: p.transaction, usd: p.amountUsd, url: p.url }),
});
PaymentRecord carries the timestamp, the amount, the onchain transaction, the network and the URL that was paid for.
What you get for the money
| Ask | Tool |
|---|
| Who is this wallet? | wallets.lookup |
| How has this KOL performed? | wallets.tracker |
| What are KOLs buying right now? | transactions.latest |
| Was this launch bundled? | bundle.get — Solana only |
| Who still holds this token? | tokens.holders |
| Which wallets moved together? | signals.list |
More than 3,000 labeled wallets, sub-500ms from trade to stream. Full reference at docs.cabalspy.xyz.
Getting a signer
Anything @x402/svm accepts — typically a KeyPairSigner from @solana/kit, or the signer your agent framework already holds:
import { createKeyPairSignerFromBytes } from '@solana/kit';
import bs58 from 'bs58';
const signer = await createKeyPairSignerFromBytes(bs58.decode(process.env.SOLANA_PRIVATE_KEY!));
Fund it with USDC on the network you selected. Gas is sponsored by the facilitator; you pay only the price.
Prefer an API key?
Then you do not need this package. Use cabalspy directly with a key from apidashboard.cabalspy.xyz — 1,000 requests free. Pay-per-call exists for agents that cannot sign up for anything.
Tests
npm test
Nineteen checks covering price parsing, both spend limits, refusal of unpriced requests, x402 v2 headers (PAYMENT-REQUIRED, PAYMENT-RESPONSE) and v1 bodies, the price probe against a server that speaks 402, and pass-through of non-402 responses. No wallet, no chain.
Related
License
MIT
