# Stock Gate — agent preflight API
Base mainnet (8453). Coinbase-issued tokenized stocks only. Read-only, USDC buy quotes; no wallet required. Never executes a trade. Independent project.

Discovery: https://base-token-lens-phs6048.amazonlightsail.com/stock-gate/openapi.json
JavaScript client: https://base-token-lens-phs6048.amazonlightsail.com/stock-gate/client.mjs
Current payment config: https://base-token-lens-phs6048.amazonlightsail.com/api/v1/stocks/config
Supported catalog: https://base-token-lens-phs6048.amazonlightsail.com/api/v1/stocks/catalog

FREE GET https://base-token-lens-phs6048.amazonlightsail.com/api/v1/stocks/check?address=0xb20000000000000000000078ee7ce2fe4908108c&amountUsdc=100
FREE GET https://base-token-lens-phs6048.amazonlightsail.com/api/v1/stocks/batch?addresses=0xb20000000000000000000078ee7ce2fe4908108c&amountUsdc=100
PAID GET https://base-token-lens-phs6048.amazonlightsail.com/api/v1/stocks/report?address=0xb20000000000000000000078ee7ce2fe4908108c&amountUsdc=100

Discovery probes: the canonical /api/v1/stocks/report URL without query parameters returns 402 metadata, including a valid input example. It is not a report request. Signed requests without address are rejected before verification or settlement.

Inputs: address is a nonzero 20-byte Base token contract. Batch addresses is a comma-separated string, 1–5 entries; duplicates share work but preserve order. amountUsdc defaults to string "100", range 0.01–1000000, max 6 decimal places. This is the hypothetical BUY order amount, NOT the API fee. Only Base USDC is quoted. Unknown/duplicate keys rejected. Batch concurrency 2. Identical token/amount quote work is cached for up to 10s with original source timestamps; provider 429 backoff is respected. Rate budget shared with Token Lens: 20 token inspections/IP/minute per Worker instance, not a global guarantee. Provider quotas also apply.

Decision pass/review/block; eligibleForQuote true only for pass. Check status per batch item, exact address, chain, order amount, checkedAt and expiresAt. HTTP 200 and complete=true mean requests completed, not that checks passed. Missing/stale NAV, quote failure or closed US regular session requires review. Unsupported issuer catalog address blocks within this service's supported universe; it does not establish fraud. Unknown never means safe. pass is a screening-policy result, not safety, suitability, eligibility or permission to trade.

Identity: exact contract match against all pages of Coinbase public stock catalog; checkedAt preserved, 30s cache. Listing does not prove current transfer or redemption eligibility. NAV is a total-return token reference already adjusted by multiplier; NEVER multiply nav_price by multiplier again. sharesPerToken converts token units to underlying share-equivalent units. NAV can freeze at night/weekends/holidays/corporate actions. premiumToReferencePercent is a comparison to a dated reference, never guaranteed arbitrage or a raw live stock price.

Quote: KyberSwap read-only route (LI.FI advanced/routes fallback if unavailable), Base USDC in / requested stock token out, exact atomic input and timestamp validated. No calldata, wallet, signature or transaction generated. LI.FI fallback requests indicative routes without wallet addresses or transaction-building calls. Its timestampSource=response_received_at is an HTTP receipt time, not a provider price timestamp; this always adds QUOTE_PROVIDER_TIMESTAMP_UNAVAILABLE and requires review. Both providers have independent quotas; if both fail, paid reports return 503 without a challenge. estimatedSpotImpactPercent compares effective quote USD/token to the largest observed pool's spot price from DEX Screener. It includes routing, fees and timing differences; not an exact simulation or slippage guarantee. gasToOrderPercent uses the provider USD input estimate, allowing USDC depegs.

Market: NYSE published US equity regular schedule, America/New_York, 2026–2028 holidays and early closes. Not a live exchange status, extended-hours feed or per-stock halt check. Corporate-action pause tracking is limited to currently exposed issuer fields; not a complete event alert service.
Policy: {"maxNavAgeSeconds":900,"maxQuoteAgeSeconds":120,"minLiquidityUsd":25000,"maxAbsolutePremiumPercent":3,"maxEstimatedSpotImpactPercent":2,"maxGasToOrderPercent":2}. A short NAV freshness threshold is deliberately conservative even though the issuer feed heartbeat can be 24h. No custom policy input in v1.
Output contains schemaVersion, modelVersion, chain, address, order, identity, reference, marketSchedule, quote, liquidity, reasons, policy, checkedAt, expiresAt. Free summaries include source status; paid reports add provenance URLs and interpretation evidence.

x402 v2 exact: 0.001 USDC (1000 atomic), Base USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, recipient 0x0F587435fd933646aD250CeD9587169513a07306. Use an official x402 client with a buyer signer; a 402 supplies PAYMENT-REQUIRED, signed retry uses PAYMENT-SIGNATURE, settlement receipt uses PAYMENT-RESPONSE. AmountUsdc is NOT this fee. No arbitrary receipt bypass. Issuer identity, NAV and fresh bound quote are preflighted before a challenge; insufficient evidence returns 503 without requesting payment. Closed session/stale NAV can still be a valid review report; payment is for screening, not a pass. Do not blindly repeat an ambiguous settlement.
ACP: free Stock Gate resources are registered under the existing Base Token Lens agent. Paid Stock Gate reports use the HTTP x402 endpoint; the ACP paid base_token_risk_report remains a different, single-token security product.

Errors: 400 invalid address/amount/unknown or duplicate query key; 429 Retry-After; 503 catalog/provider/evidence/payment unavailable, fail closed. No API call executes a trade. Not investment advice or a safety guarantee.
Sources: https://docs.base.org/sdks/tokenized-stocks/overview ; https://docs.base.org/build-on-base/integrate-defi/list-tokenized-stocks ; https://www.nyse.com/trade/hours-calendars ; https://api-docs.kyberswap.com/aggregator-api.html