# Base Screener API
# Version: 1.0.0
# Updated: 2025

## What this is
A GraphQL API for discovering and analyzing tokens on Base L2.
Designed for autonomous AI agents. Payments via x402 protocol (USDC on Base, gasless via Permit2).
No API keys required for production. No subscriptions. Pay per query in USDC.
Developer API keys available for testing — contact team for access.

## Endpoint
POST https://apitoken.agentchaintools.xyz/graphql

## Authentication
This API uses the x402 payment protocol.
1. Send your GraphQL query without a payment header.
2. Receive HTTP 402 with a PAYMENT-REQUIRED header containing Permit2 signature requirements.
3. Sign the payment authorization gaslessly using your Base wallet (Permit2 / EIP-2612).
4. Retry the request with the PAYMENT-SIGNATURE header (base64-encoded JSON payload).
5. Coinbase's facilitator verifies the signature and settles the USDC transfer gaslessly.
6. Receive your data.

Alternative: Pass X-API-Key header for credit-based access during development.

USDC contract on Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Payment recipient: 0xa6E47b07c42bcD68c3D8C97A6161bC831daD8D17
Cost per complexity unit: 0.00002 USDC
Minimum charge: 0.002 USDC per query

## Compatible agent frameworks
- Coinbase AgentKit: handles the 402 → sign → retry cycle automatically
- Any viem/ethers wallet can construct the Permit2 signature manually
- x402-client npm package for simplified integration

## GraphQL schema (abbreviated)
Query {
  token(address: String!): Token
  newTokens(minLiquidityUsd: Float, maxAgeSeconds: Int, dex: Dex, limit: Int, offset: Int): TokenList
  trending(period: Period, limit: Int): TokenList
  movers(period: Period, direction: Direction, limit: Int): TokenList
  search(query: String!, limit: Int): [Token]
  pairs(tokenAddress: String!, limit: Int): [Pair]
}

Token {
  address, symbol, name, decimals, totalSupply, deployedAt, chain
  price { usd, change1h, change24h, change7d }          # +3 complexity
  largestPool { address, dex, liquidityUsd, volumeUsd24h, txCount24h, buys24h, sells24h } # +3 complexity
  liquidity { usd, change24h }                           # +3 complexity
  volume { usd24h, txCount24h, buys24h, sells24h }       # +2 complexity
  risk { score, isHoneypot, isMintable, isVerified, liquidityLocked, top10HolderPct }  # +10 complexity
  holders { count, top10Pct }                            # +8 complexity
  pairs { address, dex, feeTier, createdAt }
}

enum Dex { UNISWAP_V2, UNISWAP_V3, UNISWAP_V4, AERODROME, BASESWAP, ALL }
enum Period { H1, H6, H24, D7 }
enum Direction { UP, DOWN }

## Example query
{
  newTokens(maxAgeSeconds: 3600, minLiquidityUsd: 10000, limit: 10) {
    tokens {
      address
      symbol
      price { usd change24h }
      largestPool { dex liquidityUsd volumeUsd24h }
      risk { score isHoneypot }
      liquidity { usd }
    }
  }
}

## Complexity pricing
Each field has a cost in complexity units. You only pay for the fields you request.
- Base fields (address, symbol, name): 0 units (free)
- price, liquidity: 3 units each
- volume: 2 units
- holders: 8 units
- risk: 10 units
- Query base costs: newTokens/trending/movers = 5, search = 2, token = 1

## Introspection
GET https://apitoken.agentchaintools.xyz/schema
Returns the raw GraphQL SDL. No payment required. Cached for 1 hour.

Standard GraphQL introspection (__schema, __type) is also free.

## Health check
GET https://apitoken.agentchaintools.xyz/health
Returns { "status": "ok" }. No payment required.

## Data sources
- Token discovery: Goldsky subgraph indexing Uniswap V2, V3, V4, and Aerodrome on Base
- Price/volume/liquidity: DexScreener API, updated every 10 minutes
- Risk analysis: Honeypot.is + Basescan, updated every 5 minutes
- Holder data: Basescan APIs

## Full documentation
https://apitoken.agentchaintools.xyz/docs