# Bot integration / Base Token Lens

Free, read-only Base mainnet (8453) screening. No wallet, signing or payment required for these endpoints. No trade is executed.

## Before a buy
GET https://base-token-lens-phs6048.amazonlightsail.com/api/v1/pretrade?address=0x4200000000000000000000000000000000000006

decision: pass | review | block
eligibleForQuote: true only when decision is pass. This means the configured screening policy passed; it is not permission to trade or a safety guarantee. Recheck freshness immediately before requesting a quote. A quote, transaction simulation and your own risk controls remain necessary.
review: missing/stale evidence, provider failure, unknown required check, unconfirmed simulation or medium privileged-control / young-pool risk.
block: observed high/critical signal or a policy threshold violation.
reasons: stable code, level and optional checkId. A block takes priority over review.

Defaults: maxRiskScore=19, minCoveragePercent=90, minLiquidityUsd=25000, maxBuyTaxPercent=5, maxSellTaxPercent=5.
GET policy overrides use numeric query parameters with these names. POST uses a policy object. Thresholds do not disable high/critical signal blocks or required-evidence checks. Taxes are percentage points, not fractions. Liquidity is the largest observed pool, not guaranteed exit liquidity. The upstream risk model applies its own penalties.

## Batch (1–5 tokens)
GET https://base-token-lens-phs6048.amazonlightsail.com/api/v1/batch?addresses=0x4200000000000000000000000000000000000006,0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

POST https://base-token-lens-phs6048.amazonlightsail.com/api/v1/batch
Content-Type: application/json
{"addresses":["0x4200000000000000000000000000000000000006","0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],"policy":{"minLiquidityUsd":50000}}

Results preserve input order and include one decision and free summary per input. Duplicates count toward the 5-input limit but share provider requests. Two unique tokens are loaded concurrently. complete=false means at least one item failed; HTTP 200 does not imply every item succeeded. An item status=error must never be treated as pass. All items unavailable: HTTP 503. Successful source responses may still contain unknown checks and yield review.
Maximum JSON body: 4096 bytes. Unknown keys, invalid policies and invalid addresses are rejected before provider requests. 429 includes Retry-After. The rate limit is 20 token inspections per IP per minute per Worker instance, shared with scan/report; it is not a guaranteed global quota. Providers have independent quotas. Data can be cached for 60 seconds; timestamps are preserved. Check expiresAt for each result, including after a batch.

## JavaScript / Node 20+
Download https://base-token-lens-phs6048.amazonlightsail.com/examples/bot-client.mjs and import it locally:

import {inspectBeforeBuy, inspectBatch, isUsableGate} from './bot-client.mjs';
const origin = 'https://base-token-lens-phs6048.amazonlightsail.com';
const token = '0x4200000000000000000000000000000000000006';
const gate = await inspectBeforeBuy(origin, token);
if (!gate.eligibleForQuote || !isUsableGate(gate, token)) {
  console.log('Stop for review', gate.decision, gate.reasons ?? gate.error);
} else {
  console.log('Screening passed; continue with your quote and simulation checks.');
}
const batch = await inspectBatch(origin, [token]);
for (const item of batch.results) console.log(item.address, item.decision, item.eligibleForQuote);

The helper fails closed on HTTP errors, wrong address/chain/schema, stale evidence, or unexpected output. Batch transport/schema errors throw; catch them and stop the trading workflow. Never treat exceptions or missing fields as permission to continue.

## Detailed reports and registration
The new endpoints contain free summaries and policy decisions, not paid evidence. Detailed HTTP report: 0.001 USDC via x402 at /api/v1/report?address=... . Existing ACP base_token_risk_report: one token per job, 0.01 USDC. These remain separate purchase routes; do not pay both for the same job. New batch/pretrade HTTP endpoints are not separate registered ACP paid offerings.
OpenAPI: https://base-token-lens-phs6048.amazonlightsail.com/openapi.json
Agent guide: https://base-token-lens-phs6048.amazonlightsail.com/llms.txt