# langchain-blockchainiq

LangChain tools for [Blockchain IQ](https://www.blockchainiq.co/agents)'s pay-per-call crypto data API. The agent pays per request in USDC on Base over [x402](https://www.x402.org). There's no account and no API key: a wallet holding a few cents of USDC is the only credential.

Made by **[ScrapeMole](https://scrapemole.pages.dev)**. MIT licensed. Not affiliated with Blockchain IQ.

| Tool | Resource | Price | What it returns |
| --- | --- | --- | --- |
| `blockchainiq_market_brief` | `GET /api/x402/v1/brief` | $0.01 | BTC, ETH, SOL, XRP prices with 24h/7d/30d moves, events in the next 48h, risk flags |
| `blockchainiq_event_risk` | `GET /api/x402/v1/event-risk` | $0.05 | Scheduled US data releases, central-bank decisions, Treasury auctions, crypto and regulatory milestones (1-90 days) |
| `blockchainiq_catalog` | `GET /api/x402/v1` | free | Every resource with its price |

## Install

```bash
git clone https://scrapemole.pages.dev/code/blockchainiq-langchain.git
cd blockchainiq-langchain
python -m venv .venv && . .venv/bin/activate
pip install -e ".[test]"
```

Requires Python 3.10+. Dependencies: `langchain-core`, `x402[evm]` (Coinbase's x402 SDK), `eth-account`, `requests`.

## Make one paid call ($0.01)

```bash
export AGENT_PRIVATE_KEY=0x...   # a dedicated Base wallet holding >= $0.01 USDC; no ETH needed
python examples/paid_call.py
```

Output (real run, 26 Oct 2026):

```
quoted price for /brief: 0.01 USDC
 BTC  $80,254  24h -0.26304%
 ETH  $2,327.17  24h -0.46879%
 SOL  $101.31  24h 0.18469%
 XRP  $1.29  24h -0.61555%
events next 48h: 2, flags: ['1 high-importance event in the next 48h: FOMC rate decision (2026-10-28 14:00 ET)']
settlement network: eip155:8453
payer: 0xCb535d13C7fC5Fe6C2B88da3f3601B840CCaf8Bc
transaction: 0xa6269f589e477345244689de339d496115b003a1a58b0bda0f0a436cb31746d4
https://basescan.org/tx/0xa6269f589e477345244689de339d496115b003a1a58b0bda0f0a436cb31746d4
```

## Use in an agent

```python
from langchain.agents import create_agent
from langchain_blockchainiq import BlockchainIQClient, get_blockchainiq_tools

tools = get_blockchainiq_tools(BlockchainIQClient(max_usdc_per_call="0.05"))
agent = create_agent("openai:gpt-4.1-mini", tools=tools)
agent.invoke({"messages": [{"role": "user", "content": "What's the crypto market doing, and what events are coming up?"}]})
```

See `examples/agent.py`. Each tool is a normal LangChain `BaseTool`, so it works with `bind_tools`, LangGraph and any tool-calling model. Paid tools return JSON with `data` plus a `payment` object (`transaction`, `network`, `payer`), so the agent can cite its proof of payment.

## How payment works

1. The tool sends a plain `GET`. Blockchain IQ answers **HTTP 402** with a `PAYMENT-REQUIRED` header naming the price, USDC on Base (`eip155:8453`) and the address to pay.
2. Coinbase's `x402` SDK signs an EIP-3009 USDC authorization for exactly that amount, locally, and retries with a `PAYMENT-SIGNATURE` header. Settlement is gasless for the payer.
3. The response is **HTTP 200** JSON plus a `PAYMENT-RESPONSE` header with the settlement transaction hash, which the tool returns.

A 404 or an error response is never charged.

## Spend safety

- `BlockchainIQClient(max_usdc_per_call=...)` (default `0.05`) is enforced twice, as an x402 payment policy and as SDK spend controls. A dearer quote is refused **before anything is signed**.
- `client.quote(path)` reads the price from the unpaid 402 for free.
- The key is read from `AGENT_PRIVATE_KEY` (or passed in) and only used to sign locally. Use a dedicated wallet with a small balance, never a main wallet.

## Tests (free, no wallet)

```bash
python -m pytest -q   # catalog, the free 402 quote, tool schemas, missing-key error
```

## Credits

Built by ScrapeMole (https://scrapemole.pages.dev), which also sells pay-per-call scraping APIs for agents over x402. Data and API by Blockchain IQ (https://www.blockchainiq.co). Market data, not investment advice.