cabalspy-x402 0.1.0

x402 client for the CabalSpy KOL API — AI agents pay per request in USDC, no account or API key. Query KOL, smart money and whale wallets on Solana, Base, BNB Chain, Ethereum and Robinhood Chain, with built-in spend limits.

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.

pip install "cabalspy-x402[all]"

Quick start

from cabalspy_x402 import create_client

cabalspy = create_client(
    svm_signer=signer,             # Solana
    max_spend_total="$5.00",       # hard cap for this process
)

wallet = cabalspy.wallets.lookup("As7HjL7dzzvbRbaD3WCun47robib2kmAKRXMvjHkSMB5")
print(wallet["name"], wallet["type"])          # Otta kol

print(cabalspy.x402.summary())
# {'calls': 1, 'spent_usd': 0.01, 'remaining_usd': 4.99}

The returned object is a full cabalspy client: every endpoint, every type, every error class. Only the payment differs.

For agents that already run an event loop:

from cabalspy_x402 import create_async_client

async with await create_async_client(svm_signer=signer) as cabalspy:
    signals = await cabalspy.signals.list(blockchain="solana", type="kol", mode="cluster")

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
max_spend_per_call	$0.10	refuses any single call priced above it
max_spend_total	$10.00	refuses further calls once reached

The price is read from the 402 response and checked before the wallet signs anything. A server asking for more than expected is refused without spending a cent.

from cabalspy_x402 import SpendLimitError

try:
    cabalspy.signals.list(blockchain="solana", type="kol", mode="cluster")
except SpendLimitError as err:
    print(err.kind, err.amount_usd, err.limit_usd)   # 'total' 9.99 10.0

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:

create_client(svm_signer=solana_signer)                  # Solana only
create_client(evm_signer=evm_signer)                     # Base, Polygon, Arbitrum
create_client(svm_signer=..., evm_signer=...)            # all four, recommended
create_client(svm_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 first

create_client(svm_signer=signer, networks=["solana-devnet"])

No real money moves, and the whole flow is identical.

Installing the payment schemes

The chain packages are optional extras, so you only pull in what you use:

pip install "cabalspy-x402[solana]"   # Solana
pip install "cabalspy-x402[evm]"      # Base, Polygon, Arbitrum
pip install "cabalspy-x402[all]"      # both

The Solana extra pins solana<0.40. That release removed solana/rpc/api.py, which the x402 SVM mechanism imports; 0.38 and 0.39 still have it and allow the solders 0.27 that x402 needs. Without the pin the install resolves to something that imports but cannot register a Solana scheme.

Your own ledger

Every settled payment is reported, so you can record it alongside whatever else your agent does:

create_client(
    svm_signer=signer,
    on_payment=lambda p: log.info("paid %s on %s for %s", p.amount_usd, p.network, 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	Call
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

Nearly 2,000 labeled wallets, sub-500ms from trade to stream. Full reference at docs.cabalspy.xyz.

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

python3 test_x402_client.py

Thirteen checks covering price parsing, both spend limits, the CAIP-2 identifiers, and reading a price from a real 402 body. No wallet, no chain.

Related

• cabalspy — the SDK, Python
• cabalspy on npm · cabalspy-x402 — TypeScript
• cabalspy on crates.io — Rust
• CabalSpy MCP Server — for Claude, Cursor and other assistants

License

MIT