# blockINT.ai — LLM / Agent Integration Guide

blockINT.ai provides blockchain threat intelligence from the C3 (Crypto Complaint Center) — 64,000+ community-verified fraud reports. Screen addresses and domains, search reports, and file new intelligence for free.

Powered by Block6IQ. Designed for AI agents, security teams, compliance tools, and on-chain investigators.

## Core Value for Agents
- Primary access: **x402 micropayments** — no API key, no registration required
- `POST /api/v1/c3-reports` is **ALWAYS FREE** and accepts anonymous submissions
- Supports Base (eip155:8453) and Solana mainnet
- Uses Coinbase CDP x402 facilitator (CDP preferred by agentic.market)
- Bazaar extension live in 402 challenges for rich discovery on agentic.market

## Primary Resources (start here)

- Full technical reference: https://blockint.ai/api/v1/reference
- x402 pricing manifest: https://blockint.ai/.well-known/x402.json
- x402 status endpoint: https://blockint.ai/api/v1/x402/status
- MCP Server Card: https://blockint.ai/.well-known/mcp/server-card.json
- Agent Skills index: https://blockint.ai/.well-known/agent-skills/index.json
- OpenAPI spec (with x402Payment scheme): https://blockint.ai/openapi.json
- ACP (Agent Commerce Protocol): https://blockint.ai/.well-known/acp.json

## Authentication

Two paths:
1. **x402 (preferred for autonomous agents)** — call without credentials → receive HTTP 402 → pay USDC → retry with X-Payment header. No registration required.
2. **bint_ API key** — 10 free calls/day via SIWE wallet connect at https://blockint.ai. Once the daily quota is exhausted the server responds with HTTP 402 (`X-Free-Tier-Exhausted: true`).

## Always-Free Endpoint

`POST https://blockint.ai/api/v1/c3-reports`
- No auth or payment required.
- Anonymous submissions accepted.
- Provide optional `x-api-key` only for attribution and leaderboard credit.

## API Base URL

https://blockint.ai/api/v1

## Key Endpoints

- `GET /screen/{address}` — Screen a blockchain address. Returns `riskScore` (0–100), `riskLevel` (critical/high/medium/low), `crimeTypes`, report count. **$0.01 USDC via x402.**
- `GET /domains/check/{domain}` — Screen a domain for phishing and fraud association. **$0.01 USDC.**
- `POST /check` — Batch screen up to 50 addresses in one call. **$0.40 USDC** ($0.008/address).
- `GET /c3-reports/search?q=<query>` — Full-text search across all community reports. **$0.01 USDC.**
- `GET /c3-reports` — Paginated list of recent public C3 reports. **$0.01 USDC.**
- `POST /c3-reports` — File a new C3 community fraud report. **Free and anonymous** — no key or payment required.
- `GET /me` — Agent stats, report count, leaderboard rank. **Free with bint_ key.**

## x402 Payment Integration

blockINT.ai uses the x402 open standard (HTTP 402 Pay-Per-Request) for micropayments.

### ⚠ Critical: Never hand-roll the PAYMENT-SIGNATURE header

The x402 v2 facilitator rejects manually constructed payment payloads with "verify failed with invalid paymentPayload". Always use the official SDK wrappers. They parse the PAYMENT-REQUIRED header, build the correct payload, sign it, and retry automatically.

### JavaScript / TypeScript (Recommended)

```
npm install @x402/fetch viem
```
```javascript
import { wrapFetch } from '@x402/fetch';
import { createWalletClient, http } from 'viem';
import { base } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const wallet = createWalletClient({ account, chain: base, transport: http() });
const fetch = wrapFetch(wallet);

const res = await fetch('https://blockint.ai/api/v1/screen/0xADDRESS');
const data = await res.json();
// data.riskScore, data.riskLevel, data.crimeTypes, data.reportCount

// Parse settlement receipt (always log for audit)
const paymentResponse = res.headers.get('payment-response');
if (paymentResponse) {
  const s = JSON.parse(Buffer.from(paymentResponse, 'base64').toString());
  console.log('Settled tx:', s.transaction, 'on', s.network);
}
```

### Python

```
pip install x402 httpx eth-account
```
```python
from x402.clients.httpx import X402HttpxClient
from x402.schemes.evm.exact import ExactEvmClientScheme
from eth_account import Account
import os

# Note: verify import paths match your installed x402 version
# python -c "import x402; help(x402)"
account = Account.from_key(os.environ['PAYER_PRIVATE_KEY'])
client = X402HttpxClient(account)
client.register_scheme(ExactEvmClientScheme())

response = client.get('https://blockint.ai/api/v1/screen/0xADDRESS')
data = response.json()
```

### Always-Free Fraud Report (curl)

```bash
curl -X POST https://blockint.ai/api/v1/c3-reports \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Phishing campaign",
    "description": "Detailed description...",
    "crimeType": "phishing",
    "scammerAddresses": ["0x..."],
    "reportedDomains": ["evil.example"],
    "amountLost": 12500
  }'
```

### Payment Networks

| Network | CAIP-2 | Receiving wallet | USDC contract |
|---------|--------|-----------------|---------------|
| Base mainnet | eip155:8453 | 0x32984663A11b9d7634Bf35835AE32B5A031637D5 | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
| Solana mainnet | solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp | 2JJZcG2Zv9s8oatD7FRRwpmGAPEcgcXt4zGNvKDqTz66 | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v |

### Three Buyer Flows

1. **Keyless agent**: Call endpoint → receive 402 → SDK pays → receive 200 + settlement receipt
2. **API key free tier**: Send `x-api-key: bint_...` → 10 free calls/day → track with `X-RateLimit-Remaining-Day`
3. **Key + x402 fallback**: Free tier exhausted → 402 with `X-Free-Tier-Exhausted: true` → SDK pays → 200

### Troubleshooting

- **"invalid paymentPayload"**: Never hand-roll the payment header. Use the SDK.
- **402 after payment**: Wrong network (must be eip155:8453), insufficient USDC balance, or SDK version mismatch (upgrade to latest @x402/fetch).
- **Insufficient funds**: Payer wallet needs USDC on Base mainnet and a small amount of ETH for gas.
- **Python ImportError**: Run `pip install --upgrade x402` then `python -c "import x402; help(x402)"` to verify import paths.

### PAYMENT-RESPONSE header

When a payment is charged, the server returns `payment-response` header (base64 JSON) containing:
- `transaction` — on-chain tx hash
- `network` — CAIP-2 chain ID (e.g. eip155:8453)
- `payer` — EVM address of the paying wallet
- `success` — boolean settlement confirmation

Absence of the header means the request was served from the free tier.

## Bazaar Extension

Live in 402 challenges for rich discovery on agentic.market. The extension provides `serviceName`, `tags`, input/output schemas, and examples for each endpoint — enabling enriched auto-listing without manual submission.

## Attribution

Commercial use requires attribution to Block6IQ / blockINT.ai.

Data provider: https://block6iq.com — sovereign blockchain intelligence infrastructure.

---
For full details, always prefer https://blockint.ai/api/v1/reference over this file.