---
name: x402-proxy
description: x402 gateway on Base with live raw paid API endpoints, paid workflow signals, and dynamic request-priced batches. Discover available services at GET /.
metadata:
  homepage: https://tell.pawr.link
  network: eip155:8453
  asset: USDC
  requires:
    packages: ["@x402/fetch", "@x402/evm", "viem"]
---

# tell.pawr.link

Workflow signals package sourced crypto, social, and onchain answers over x402. AI utilities turn public URLs into structured agent-readable JSON. Live raw primitive endpoints stay available for custom builds.

No accounts. No API keys. Your wallet is your identity.

## Workflow signals

Packaged buying surfaces with one x402 payment, deterministic validation, source receipts, and cache-aware pricing.

| Signal | Job | Fresh price | Cache policy | Status |
|--------|-----|-------------|--------------|--------|
| Checkr Radar Signal | Which Base tokens are moving on attention, velocity, and rotation? | $0.15 | HIT free for 5m | Live: `POST /signals/checkr-radar` |
| Narrative Conviction Signal v0 | Is this token attention organic, durable, and market-aligned? | $0.75 | HIT free for 10m | Live: `POST /signals/narrative-conviction` |
| Smart Money + Attention Signal | Are feeds and wallets agreeing? | $0.75–$1.50 | HIT free inside TTL | Planned |

MISS = paid fresh result. HIT = free cached repeat inside TTL.

Workflow signals are decision-support artifacts, not financial advice. They return cited signals and caveats; they do not place trades, sign transactions, or submit swaps.

## AI utilities

Small paid AI/metadata jobs for agents. V1 routes are narrow, structured, and bounded: public URL-only, no arbitrary browser/tool execution, and no private/internal hosts.

| Utility | Job | Fresh price | Cache policy | Status |
|---------|-----|-------------|--------------|--------|
| Product Extract | Public product URL → schema.org/Product-like JSON with evidence and warnings | $0.02 | HIT free for 24h | Live: `POST /ai/extract-product` |

`POST /ai/extract-product` request:

```json
{
  "url": "https://example.com/product",
  "includeEvidence": true
}
```

Response shape:

```json
{
  "url": "https://example.com/product",
  "canonicalUrl": "https://example.com/product",
  "extractedAt": "2026-05-12T00:00:00.000Z",
  "product": {
    "name": "Example Product",
    "description": "Short product description",
    "brand": "Example Brand",
    "sku": "ABC-123",
    "price": "19.99",
    "currency": "USD",
    "availability": "https://schema.org/InStock",
    "images": ["https://example.com/product.jpg"],
    "variants": []
  },
  "evidence": {
    "title": "Example Product | Example Store",
    "metaDescription": "Short product description",
    "jsonLdTypes": ["Product"]
  },
  "warnings": []
}
```

Safety boundaries: `http:`/`https:` only; localhost, private IPs, link-local/metadata IPs, `.local`, and single-label internal hostnames are blocked. V1 extracts bounded HTML metadata only — no LLM, no headless browser, no arbitrary schema.

## Discovery

Start here. Browse what's available, then call what you need. Free, no payment.

```
GET https://tell.pawr.link/          → service catalog (JSON by default, HTML if Accept: text/html)
GET https://tell.pawr.link/skill.md  → this file
GET https://tell.pawr.link/health    → public status, Redis, accepting payments flag, coarse service counts
GET https://tell.pawr.link/activity  → recent public calls (status, latency, cache; request ids redacted)
GET https://tell.pawr.link/llms.txt  → short LLM-friendly index
GET https://tell.pawr.link/openapi.json → generated OpenAPI 3.1 route contract
GET https://tell.pawr.link/tell       → canonical standalone CLI binary script
GET https://tell.pawr.link/tell-install.sh → canonical shell install helper
GET https://tell.pawr.link/x402p      → legacy CLI binary script
GET https://tell.pawr.link/x402p-install.sh → legacy shell install helper
curl -fsSL https://tell.pawr.link/tell-install.sh | bash → recommended hosted standalone install
```

The catalog returns every provider, endpoint, price, cache TTL, **parameter metadata** (name, type, required, description, example, enum/min/max), and a **response example** for the most common services. It also includes a `meta` block listing all free routes and common error codes — agents can use the catalog alone to construct correct calls without reading this file.

The catalog has a `meta.schemaVersion` so consumers can detect breaking changes. New providers and parameter annotations show up automatically.

**Catalog response (trimmed):**

```json
{
  "name": "tell.pawr.link",
  "network": "eip155:8453",
  "asset": "USDC",
  "markup": "10%",
  "providers": [
    {
      "slug": "checkr",
      "name": "Checkr Social",
      "description": "CT attention intelligence for Base tokens",
      "services": [
        {
          "id": "checkr/spikes",
          "method": "GET",
          "endpoint": "https://tell.pawr.link/checkr/spikes",
          "price": "$0.055",
          "currency": "USDC",
          "cacheTTL": 60
        }
      ]
    }
  ]
}
```

## Caching

**MISS = paid fresh result. HIT = free cached repeat inside TTL.**

Each service has a `cacheTTL` (seconds). Within the TTL window, identical requests return instantly with `X-Cache: HIT` — the agent never pays twice for the same data.

- Check the `X-Cache` response header: `HIT` = free, `MISS` = paid
- Cache key = path + sorted query params + POST body hash
- `cacheTTL: 0` means no cache (every call pays)
- `cachePolicy` in the catalog describes each service's behavior

**Tip:** Call the endpoint once, then call it again within the TTL. If the second call returns `X-Cache: HIT` in <5ms, caching works.

## Quickstart (CLI-first)

```bash
# 1) Install hosted standalone tell
curl -fsSL https://tell.pawr.link/tell-install.sh | bash

# 2) Configure key source for paid calls (recommended)
export X402_PRIVATE_KEY_CMD='secret-tool lookup app x402 wallet main'

# 3) Discover + inspect without paying
tell doctor --json
tell list --json
tell show signals/checkr-radar --json

# 4) No-pay workflow probe: verifies route shape/pricing without settlement
tell call signals/checkr-radar --method POST --json '{"symbols":["AERO"],"limit":1}' --max-price 0.15 --no-pay

# 5) Paid workflow signal after explicit approval/spend budget
tell call signals/checkr-radar --method POST --json '{"symbols":["AERO","VIRTUAL"],"limit":8}' --max-price 0.15

# 6) Custom bundle: quote one dynamically priced x402 payment for multiple endpoints
tell batch checkr/leaderboard checkr/spikes --max-price 0.10 --no-pay
```

This is the recommended path for autonomous agents: less glue code, safer secret handling, stable JSON output, and guardrails.

## Public no-spend watchdog

Run from the repo when checking the live public path without spending USDC:

```bash
npm run smoke:public:no-pay
```

It validates health/snapshot/catalog/OpenAPI, hosted install docs, bundled `/tell`, isolated installer execution, `tell doctor/list/show`, and a no-pay `signals/checkr-radar` call that must return `402` with `paymentResponsePresent=false`.

## SDK quickstart (optional)

Use this only when you need custom transport/runtime behavior that `tell` doesn't cover.

```typescript
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:*", client: new ExactEvmScheme(privateKeyToAccount(PRIVATE_KEY)) }],
});

const res = await fetchWithPayment("https://tell.pawr.link/checkr/spikes");
const data = await res.json();
```

**Example response** (cache miss — first call):

```
HTTP/1.1 200 OK
X-Cache: MISS
X-Upstream-Price: $0.05
X-Your-Price: $0.055
```
```json
[
  { "symbol": "AERO", "spike": 4.2, "mentions_1h": 87, "mentions_prior": 21 },
  { "symbol": "VIRTUAL", "spike": 3.1, "mentions_1h": 63, "mentions_prior": 20 }
]
```

Subsequent calls within 60s return the same data instantly with `X-Cache: HIT` — no payment.

Your wallet needs USDC on Base. Bridge via [bridge.base.org](https://bridge.base.org) or buy on [Coinbase](https://coinbase.com).

## Agent CLI (tell)

For autonomous agents, `tell` gives one stable command surface for discovery + paid calls. `x402p` remains supported as the legacy compatibility command.

Install:

```bash
curl -fsSL https://tell.pawr.link/tell-install.sh | bash
# legacy compatibility also remains available
curl -fsSL https://tell.pawr.link/x402p-install.sh | bash
```

Setup:

```bash
# required for paid calls (choose one key source)
# RECOMMENDED: command-based retrieval (no raw key in env/scripts)
export X402_PRIVATE_KEY_CMD='secret-tool lookup app x402 wallet main'
# or
export X402_PRIVATE_KEY_FILE=/secure/path/x402.key
# or (least preferred)
export X402_PRIVATE_KEY=0x...64hex...

# optional defaults
export TELL_BASE_URL=https://tell.pawr.link  # X402P_BASE_URL also supported for compatibility
export TELL_MAX_PRICE=0.25  # X402P_MAX_PRICE also supported for compatibility
```

Commands:

```bash
tell doctor --json
tell list --json
tell show checkr/spikes --json
tell call checkr/token/:symbol --param symbol=AERO --max-price 0.60
tell combine checkr/leaderboard checkr/token/:symbol --query 1.limit=10 --param 2.symbol=AERO --max-price 0.10
tell batch checkr/leaderboard checkr/spikes --max-price 0.10
tell call signals/checkr-radar --method POST --json '{"symbols":["AERO"],"limit":5}' --max-price 0.15
tell call signals/narrative-conviction --method POST --json '{"symbol":"AERO","network":"base","coingecko_id":"aerodrome-finance"}' --max-price 0.75
tell call checkr/leaderboard --no-pay
```

Machine behavior:
- JSON output by default
- Exit codes: `0` success, `2` usage/validation error, `3` price guard blocked, `4` payment required/verify error, `5` request/upstream failure

### Custom endpoint bundles

Agents can choose primitives from the catalog. `tell combine` pays/calls sequentially from the CLI. `tell batch` sends the same plan to `POST /batch` and receives one dynamic request-priced x402 payment for the whole bundle:

```bash
tell batch checkr/leaderboard checkr/token/:symbol \
  --query 1.limit=10 \
  --param 2.symbol=AERO \
  --max-price 0.10
```

Use numeric scopes (`1.`, `2.`, etc.) to attach query/path/body values to each endpoint. The total `--max-price` guard is checked locally before any request is sent and forwarded as `max_price_usdc` for gateway-side rejection before payment. Output includes `mode: "batch"`, dynamic price fields, `serviceIds`, and per-endpoint `results[]`. Use `POST /batch/quote` or `tell batch ... --no-pay` for a free quote of the same JSON body. Batch honors cache per item: HIT items price at `0`, all-HIT plans skip payment, and settlement-blocked partial failures redact per-item data.

## Services

Two kinds of services live here:

- **Owned** — endpoints we host directly. No upstream payment, no markup. The price you see IS the price you pay.
- **Proxied** — third-party x402 services we relay. Upstream price + 10% gateway fee.

The catalog at `GET /` shows which is which via the provider's `type` field. Owned responses include only `X-Your-Price`; proxied responses include both `X-Upstream-Price` and `X-Your-Price`.

---

### Swap Quotes — best DEX quote across multiple aggregators (OWNED)

Queries Fabric, Odos, and KyberSwap in parallel, simulates each quote against the chain, and returns the best-price one. One call instead of integrating six aggregators yourself.

| Endpoint | Price | Cache | Returns |
|----------|-------|-------|---------|
| `GET /swap/quote` | $0.020 | 2s | Best swap quote (provider, output amount, gas estimate, txData, approval info) |

**Required query params:**
- `chainId` — EIP-155 chain ID (e.g., `8453` for Base)
- `inputToken` — 0x address of token to sell
- `outputToken` — 0x address of token to buy
- `inputAmount` — amount in base units (string, BigInt-safe)
- `slippageBps` — 0-10000 (e.g., `50` = 0.5%)
- `swapperAccount` — 0x address that will execute the swap (must hold the input token for simulation to succeed)

**Example:**

```
GET /swap/quote?chainId=8453&inputToken=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&outputToken=0x4200000000000000000000000000000000000006&inputAmount=1000000&slippageBps=50&swapperAccount=0xYourWallet
```

Returns 1 USDC → WETH best quote on Base. Response includes `provider`, `outputAmount`, `networkFee`, `txData` ready to submit, and `approval` info if the spender needs approval first. BigInts are returned as strings (parse back with `BigInt()`).

Powered by [Spandex](https://spandex.sh).

---

### Checkr Social — CT attention intelligence

Which Base tokens are getting attention on Crypto Twitter right now.

| Endpoint | Price | Cache | Returns |
|----------|-------|-------|---------|
| `GET /checkr/leaderboard` | $0.022 | 5m | Top tokens ranked by social attention |
| `GET /checkr/token/{symbol}` | $0.550 | 3m | Full attention deep-dive for one token (10x data) |
| `GET /checkr/spikes` | $0.055 | 60s | Tokens spiking in mentions right now |
| `GET /checkr/bankr` | $0.055 | 5m | Attention on Bankr-traded tokens |
| `GET /checkr/rotation` | $0.110 | 2m | Where attention is shifting + creator crossover |

All endpoints accept query parameters — see [api.checkr.social/docs](https://api.checkr.social/docs) for details.

### CoinGecko — token prices and on-chain market data

Token prices, liquidity, and trending pools across 250+ networks. TTLs match upstream refresh rate so traders never get stale data — pay-per-call when fresh, cached only for a few seconds at most.

| Endpoint | Price | Cache | Returns |
|----------|-------|-------|---------|
| `GET /coingecko/price` | $0.011 | 3s | Aggregated prices by CoinGecko ID — `?ids=bitcoin,ethereum&vs_currencies=usd` |
| `GET /coingecko/token_price/{network}/{address}` | $0.011 | 2s | On-chain price by contract — `network` = base, solana, eth, etc. |
| `GET /coingecko/token/{network}/{address}` | $0.011 | 2s | Full token data — price, liquidity, market info |
| `GET /coingecko/trending/{network}` | $0.011 | 30s | Trending pools on a network |
| `GET /coingecko/search` | $0.011 | 60s | Search pools and tokens — `?query=...` |

### pawr.link — agent profile directory

List, search, and create agent profile pages (fetch-by-slug is not routed until upstream settlement is fixed).

| Endpoint | Price | Cache | Returns |
|----------|-------|-------|---------|
| `GET /pawr/profiles` | $0.011 | 60s | List profiles — filter by `?type=agent\|human`, paginate `?limit&offset` |
| `GET /pawr/profiles/search` | $0.022 | 60s | Search by name, bio, ENS, wallet, or Farcaster (`?q=...`) |
| `POST /pawr/profiles/create` | $1.100 | — | Create a profile (AI-built or structured). Returns claim URL |

### Nansen — Smart Money and wallet/onchain intelligence

| Endpoint | Price | Cache | Returns |
|----------|-------|-------|---------|
| `POST /nansen/smart-money/holdings` | $0.055 | 5m | Smart Money token holdings and exposure |
| `POST /nansen/smart-money/netflow` | $0.055 | 2m | Smart Money accumulation/distribution netflow |
| `POST /nansen/smart-money/dex-trades` | $0.055 | 2m | Recent DEX trades from Smart Money wallets |
| `POST /nansen/profiler/pnl-summary` | $0.011 | 5m | Wallet realized/unrealized PnL summary |
| `POST /nansen/profiler/transactions` | $0.011 | 2m | Wallet transaction history with labels/context |
| `POST /nansen/profiler/current-balance` | $0.011 | 2m | Current token holdings and USD values |
| `POST /nansen/tgm/flow-intelligence` | $0.011 | 2m | Token flow intelligence across wallet cohorts |
| `POST /nansen/tgm/who-bought-sold` | $0.011 | 2m | Buyer/seller evidence by cohort |
| `POST /nansen/token-screener` | $0.011 | 5m | Token screening by liquidity, volume, holders, and Nansen metrics |

### Zapper — wallet identity, portfolio, and social-onchain activity

| Endpoint | Price | Cache | Returns |
|----------|-------|-------|---------|
| `POST /zapper/account-identity` | $0.001238 | 5m | ENS, Farcaster, Lens, Basenames by wallet |
| `POST /zapper/portfolio-totals` | $0.002063 | 2m | Portfolio totals across tokens, apps, and NFTs |
| `POST /zapper/token-balances` | $0.001238 | 2m | Detailed token balances by wallet/chain |
| `POST /zapper/token-price` | $0.001238 | 30s | Token price and market cap by address/chain |
| `POST /zapper/token-ranking` | $0.004950 | 60s | Ranked tokens by swap activity/adoption velocity |
| `POST /zapper/transaction-history` | $0.001238 | 2m | Human-readable wallet transaction history |
| `POST /zapper/general-swap-feed` | $0.004125 | 30s | Real-time swap activity with social context |
| `POST /zapper/token-activity-feed` | $0.004125 | 30s | Token-specific swaps plus top casts/activity |

### TrustLayer — ERC-8004 agent trust/reputation

| Endpoint | Price | Cache | Returns |
|----------|-------|-------|---------|
| `GET /trustlayer/trust/{chain}/{agentId}` | $0.001100 | 5m | Full feedback forensics and Sybil/risk assessment |
| `GET /trustlayer/agent/{chain}/{agentId}` | $0.001100 | 10m | Agent profile lookup with trust metadata |
| `GET /trustlayer/score/{chain}/{agentId}` | $0.001100 | 5m | Basic trust score and component breakdown |
| `GET /trustlayer/history/{chain}/{agentId}` | $0.001100 | 10m | Trust score time series and trajectory |
| `GET /trustlayer/verified/{chain}/{agentId}` | $0.011 | 10m | Verified economic reputation and paid-work completions |

### More providers

Check the catalog (`GET /`) for the latest. New providers ship without updating this file.

Profile-update endpoints (update fields, links, AI-curate) live directly on [pawr.link](https://pawr.link) — see [pawr.link/skill.md](https://pawr.link/skill.md).

## Pricing

Upstream price + 10%. You only pay on the first call — cached responses are free. The cache saves upstream costs, which is how the gateway sustains itself.

You're never charged for failed upstream calls.

## Response headers

Every response includes headers so you know what happened:

| Header | When | Meaning |
|--------|------|---------|
| `X-Cache: HIT` | Cache warm | Free response, served from cache |
| `X-Cache: MISS` | Cache cold | Paid, fetched from upstream, now cached |
| `X-Cache-TTL` | HIT | Seconds until this cache entry expires |
| `X-Upstream-Price` | MISS | What the upstream service charged |
| `X-Your-Price` | MISS | What you paid (upstream + 10%) |

## Errors

| Status | Meaning |
|--------|---------|
| 400 | Bad request — invalid payment payload, insufficient USDC, or malformed parameters |
| 402 | Payment required — your x402 client handles this automatically |
| 404 | Service not found — response includes `suggestions` (fuzzy-matched closest paths) and a `catalog` pointer |
| 413 | Request body too large (max 1 MB) |
| 502 | Upstream unavailable — retry later (you are not charged for failed responses) |
| 503 | Service disabled — circuit breaker tripped. Response includes `retryAfter` hint and `catalog` pointer |

## Links

- **Gateway**: [tell.pawr.link](https://tell.pawr.link)
- **Catalog**: [tell.pawr.link/](https://tell.pawr.link/) (JSON)
- **Platform**: [pawr.link](https://pawr.link)

---

## How x402 works

x402 uses HTTP 402 (Payment Required) for machine-to-machine payments. USDC on Base, no accounts or API keys.

1. You call an endpoint
2. Server returns 402 with `payment-required` header (price, payTo, asset)
3. Your x402 client signs a USDC transfer authorization (off-chain, EIP-3009)
4. Client retries with `payment-signature` header
5. Facilitator settles on-chain (`transferWithAuthorization`). USDC moves from your wallet to the server.
6. Server returns data + `payment-response` header (tx hash)

Steps 2-4 are automatic with `@x402/fetch`. One `fetch()` call from your perspective.

```bash
npm install @x402/fetch @x402/evm viem
```

**Learn more:**
- [x402.org](https://x402.org) — protocol overview
- [docs.x402.org](https://docs.x402.org) — full documentation
- [github.com/coinbase/x402](https://github.com/coinbase/x402) — SDK source
- [CDP x402 quickstart](https://docs.cdp.coinbase.com/quickstart-for-buyers) — buyer guide

---

`v2.2.0` · 2026-04-11