Metadata-Version: 2.4
Name: cabalspy-x402
Version: 0.1.0
Summary: 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.
Project-URL: Homepage, https://docs.cabalspy.xyz
Project-URL: Documentation, https://docs.cabalspy.xyz
Project-URL: Repository, https://github.com/CabalSpy/cabalspy-x402-python
Project-URL: Issues, https://github.com/CabalSpy/cabalspy-x402-python/issues
Author-email: CabalSpy <contact@cabalspy.xyz>
License-Expression: MIT
License-File: LICENSE
Keywords: agent-payments,ai-agent,autonomous-agent,base,bnb,bundle-detection,cabalspy,ethereum,http-402,kol,kol-api,machine-payments,memecoin,micropayments,onchain-data,pay-per-call,robinhood-chain,sdk,smart-money,solana,trading-signals,usdc,wallet-tracker,whale-tracker,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: cabalspy>=0.2.0
Requires-Dist: httpx>=0.24
Requires-Dist: requests>=2.28
Requires-Dist: x402>=2.17
Provides-Extra: all
Requires-Dist: solana<0.40,>=0.38; extra == 'all'
Requires-Dist: x402[evm,svm]>=2.17; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: evm
Requires-Dist: x402[evm]>=2.17; extra == 'evm'
Provides-Extra: solana
Requires-Dist: solana<0.40,>=0.38; extra == 'solana'
Requires-Dist: x402[svm]>=2.17; extra == 'solana'
Description-Content-Type: text/markdown

# 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.

```bash
pip install "cabalspy-x402[all]"
```

## Quick start

```python
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`](https://pypi.org/project/cabalspy/) client: every endpoint, every type, every error class. Only the payment differs.

For agents that already run an event loop:

```python
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.

```python
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:

```python
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

```python
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:

```bash
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:

```python
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](https://docs.cabalspy.xyz).

## Prefer an API key?

Then you do not need this package. Use [`cabalspy`](https://pypi.org/project/cabalspy/) directly with a key from [apidashboard.cabalspy.xyz](https://apidashboard.cabalspy.xyz/) — 1,000 requests free. Pay-per-call exists for agents that cannot sign up for anything.

## Tests

```bash
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`](https://pypi.org/project/cabalspy/) — the SDK, Python
- [`cabalspy`](https://www.npmjs.com/package/cabalspy) on npm · [`cabalspy-x402`](https://www.npmjs.com/package/cabalspy-x402) — TypeScript
- [`cabalspy`](https://crates.io/crates/cabalspy) on crates.io — Rust
- [CabalSpy MCP Server](https://mcp.cabalspy.xyz/mcp) — for Claude, Cursor and other assistants

## License

MIT
