Metadata-Version: 2.5
Name: scrapling-data
Version: 0.1.0
Summary: Lead-magnet SDK for Scrapling Data: free address tools + x402 pay-per-call crypto intel for AI agents (USDC on Base, no API key).
Project-URL: Homepage, https://scraplingdata.xyz
Project-URL: Documentation, https://scraplingdata.xyz/docs
Project-URL: Repository, https://github.com/scraplingdata
Project-URL: Hugging Face, https://huggingface.co/scraplingdata
Project-URL: OpenAPI, https://scraplingdata.xyz/openapi.json
Project-URL: llms.txt, https://scraplingdata.xyz/llms.txt
Project-URL: x402 manifest, https://scraplingdata.xyz/.well-known/x402
Project-URL: Issues, https://github.com/scraplingdata/scrapling-data-skill/issues
Author-email: Scrapling Data <scraplingdata@mail.grokbot.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,base,crypto,defi,mcp,scrapling,usdc,wallet,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# scrapling-data

**Lead-magnet Python SDK** for [Scrapling Data](https://scraplingdata.xyz) — pay-per-call crypto & web intel for AI agents via **x402** (USDC on Base, no API key).

Install once. Get **free** local address tools and free store teasers. When you need the real answer, the same client speaks **HTTP 402 → pay → retry** against the live catalog.

- Site: https://scraplingdata.xyz
- Docs: https://scraplingdata.xyz/docs
- GitHub: https://github.com/scraplingdata
- Hugging Face: https://huggingface.co/scraplingdata
- MCP: https://scraplingdata.xyz/mcp

> This package is the **public thin SDK**. It does **not** include Scrapling's private scrapers, label builders, or secrets.

## Install

```bash
pip install scrapling-data
```

(Until published: `pip install -e /path/to/scrapling-data`)

## 30-second sticky start

```bash
# Free local checksum + free wallet-label teaser + paid price menu
scrapling-data check 0x28C6c06298d514Db089934071355E5743bf21d60

# Lookalike / address-poisoning heuristic (local, free)
scrapling-data check 0x28C6c06298d514Db089934071355E5743bf21d60 \
  --compare 0x28C6c06298d514Db089934071355E5743bf21d61
```

```python
from scrapling_data import ScraplingData, inspect_address, to_checksum_address

print(inspect_address("0x28c6c06298d514db089934071355e5743bf21d60"))
print(to_checksum_address("0x28c6c06298d514db089934071355e5743bf21d60"))

with ScraplingData() as sd:
    print(sd.free_crypto_top10())          # free
    print(sd.free_wallet_label("0x28C6c06298d514Db089934071355E5743bf21d60"))
    # Paid — raises PaymentRequiredError with accepts[] unless you attach a signer:
    # sd.counterparty("0x28C6c06298d514Db089934071355E5743bf21d60")
```

## What's free vs paid

| Layer | What you get | Cost |
| --- | --- | --- |
| **Local** | EVM validate, EIP-55 checksum, ENS/Solana detect, lookalike/poison heuristic, chain id hints | Free, offline |
| **Free API** | `/v1/free/*` teasers (wallet-label sample, hack-tracker headline, top10, yields, 3×/day risk-check, …) | Free (rate-limited) |
| **Paid API** | Full counterparty, risk-check, hack-tracker, yields, market-pulse, tokenized assets, whales, DD, … | From **$0.0009** USDC via x402 |

### Sticky funnel (by design)

1. `scrapling-data check <addr>` → valid + checksum + free label teaser.
2. See the **paid menu** with live catalog prices.
3. Call `ScraplingData(...).counterparty(addr)` (or risk-check / hack-tracker / …).
4. Without a wallet: clear **402** payload + docs link. With `payment_handler`: auto-retry with `PAYMENT-SIGNATURE`.

## Paying with x402

```python
from scrapling_data import ScraplingData, PaymentRequiredError

def my_signer(payment):
    """Return a PAYMENT-SIGNATURE string. Use your own wallet / x402 client.
    Never put a private key in this library or in source control."""
    accept = payment.preferred_accept()
    # ... sign accept with your viem / eth-account / Coinbase AgentKit / x402 SDK ...
    raise NotImplementedError("wire your signer here")

sd = ScraplingData(payment_handler=my_signer)
try:
    print(sd.counterparty("0x28C6c06298d514Db089934071355E5743bf21d60"))
except PaymentRequiredError as e:
    print(e.payment.to_dict())  # accepts, amount, payTo, how_to_pay
```

Also supported: `pass_token=` (day/month pass), `api_key=` (`Bearer sk_scrapling_...`), `trial_code=`.

Day pass **$2** · month pass **$25** · settlement payTo (EVM): `0x72C80C01fD89Bac74f47cf604b61ACd119c9BCdb`.

## Highlight paid routes (catalog hints)

Prices from live `/llms.txt` + OpenAPI (Nov 2026). **402 body is authoritative.**

| Route | USD | Use |
| --- | ---: | --- |
| `/v1/lookup/address-poisoning` | 0.0009 | Live Base USDC lookalike flags |
| `/v1/bundle/market-pulse` | 0.001 | Whole-market pulse |
| `/v1/wallet-label` | 0.002 | Full label + sources |
| `/v1/check/counterparty` | 0.004 | safe / caution / block |
| `/v1/intel/risk-check` | 0.0045 | MALICIOUS…UNKNOWN (3 free/day) |
| `/v1/wallet/profile` | 0.005 | Who is this wallet? |
| `/v1/lookup/tokenized-stocks` | 0.005 | Ondo / xStocks |
| `/v1/lookup/hack-tracker` | 0.03 | Stolen-funds tracker |
| `/v1/trust/agent` | 0.04 | Agent trust bundle |
| `/v1/dd/report` | 1.00 | Full due-diligence |
| `/v1/bundles/stolen-funds/download` | 12 | Pack download (not on passes) |

Full machine list: https://scraplingdata.xyz/llms.txt · https://scraplingdata.xyz/openapi.json

## CLI

```text
scrapling-data check <address> [--compare 0x...] [--offline] [--json]
scrapling-data catalog [--max-price 0.01]
scrapling-data ping
```

## For agents / MCP

See [`AGENT.md`](./AGENT.md). Remote MCP (same store): `https://scraplingdata.xyz/mcp`.

## License

MIT © Scrapling Data
