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:

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", allowed only when both limits are float("inf")).

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

api.cabalspy.xyz takes mainnet payments only, so a client restricted to solana-devnet finds no matching offer there. The option exists for testing create_payment_client against your own x402 endpoint.

Against CabalSpy, start with a small max_spend_total instead — at $0.01 a call, "$0.10" buys ten requests.

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

More than 3,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

pip install -e ".[all,dev]"
pytest

Sixteen checks covering price parsing, both spend limits, refusal of unpriced requests, x402 v2 headers (PAYMENT-REQUIRED, PAYMENT-RESPONSE) and v1 bodies, and the guarded client against a simulated v2 server. No funded wallet, no chain. They run in the publish workflow, so nothing reaches PyPI without them.

Related

• x402 for AI agents on cabalspy.xyz · KOL API · Smart Money API · use cases
• SDKs: TypeScript · Python · Rust
• x402 clients (pay per request, no API key): TypeScript · Python
• MCP server — for Claude, Cursor and VS Code
• CabalSpy Terminal — trade with the same wallet data

License

MIT