Codex Evidence Lab A2MCP Suite

Eight separately listable Web3 intelligence services on one shared HTTP, MCP, data, and x402 runtime. The suite is designed for the OKX.AI Codex Evidence Lab Agent and returns structured evidence instead of trading promises.

Service Catalog

Market chains: solana, ethereum, xlayer, base, bsc, arbitrum, and polygon.

EVM security chains: ethereum, xlayer, base, bsc, arbitrum, and polygon. Solana contract and holder security fields stay explicitly unavailable until a separately tested Solana security provider is connected.

Legacy callers remain compatible:

Data and Output

• DexScreener is the primary public market source.

• GeckoTerminal is the market fallback.

• GoPlus supplies EVM contract, tax, holder, owner, creator, and liquidity-holder fields.

• Provider failures return a structured partial or unavailable result before the request budget expires.

• Unknown fields remain unknown; they are never inferred as safe.

• Every successful service response includes service.id, request_id, generated_at, data_quality, and sources.

Default cache durations are 30 seconds for market data and 300 seconds for security data. The default upstream request timeout is 4 seconds and the total provider budget per service call is 4.5 seconds.

Run Locally

Requires Node.js 22.14 or newer.

npm ci
npm start

Discovery endpoints:

curl -fsS http://localhost:8787/health
curl -fsS http://localhost:8787/metadata
curl -fsS http://localhost:8787/mcp
curl -fsS http://localhost:8787/openapi.json

Every canonical service endpoint also accepts GET and HEAD for marketplace reachability checks. These discovery requests return invocation metadata only; paid execution remains a POST protected by x402.

Call the composite report:

curl -fsS -X POST http://localhost:8787/api/pretrade-risk-report \
  -H 'content-type: application/json' \
  -d '{
    "chain": "ethereum",
    "token_address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "language": "zh-CN"
  }'

Call the same tool over MCP JSON-RPC:

curl -fsS -X POST http://localhost:8787/mcp \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "pretrade_risk_report",
      "arguments": {
        "chain": "ethereum",
        "token_address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
      }
    }
  }'

Tests

npm test
npm run test:x402
npm run test:facilitator-config

npm test runs unit tests and a live demo-mode smoke test across all eight canonical routes, all three aliases, and MCP. test:x402 verifies the exact payment amount and resource URL for every paid route.

x402 Modes

PAYMENT_MODE=demo executes services without a payment challenge. mock-x402 returns test HTTP 402 challenges but never settles money. okx-x402 uses the OKX facilitator and requires real credentials.

Each canonical or legacy HTTP route uses its catalog fee. /mcp has a fixed default fee of 0.03 USDT because x402 issues the challenge before the server reads which MCP tool was selected.

Production environment shape:

PAYMENT_MODE=okx-x402
PUBLIC_BASE_URL=https://your-domain.example
OKX_API_KEY=...
OKX_SECRET_KEY=...
OKX_PASSPHRASE=...
X402_PAY_TO=0xYourReceivingAddress
X402_NETWORK=eip155:196
X402_ASSET=0x779ded0c9e1022225f8e0630b35a9b54be713736
X402_TOKEN_NAME=USDt0
X402_TOKEN_SYMBOL=USDT0
X402_TOKEN_DECIMALS=6
MCP_FEE_USDT=0.03

The code derives each minimal token amount from the service catalog and X402_TOKEN_DECIMALS; there is no global per-service amount to keep in sync manually.

Zeabur Deployment

The included Dockerfile is sufficient for a GitHub-backed Zeabur service. Configure the variables from .env.example in Zeabur, set PUBLIC_BASE_URL to the provisioned HTTPS origin, and keep .env out of Git.

Against a public demo/staging deployment, run the full response smoke test. Against a paid production deployment, run the x402 challenge test:

A2MCP_BASE_URL=https://your-staging-domain.example npm run test:smoke
A2MCP_BASE_URL=https://your-domain.example npm run test:x402

Production verification should confirm:

• /health reports version 0.3.1 and eight services.

• /metadata exposes eight distinct service descriptions and fees.

• /openapi.json contains every canonical path.

• GET and HEAD return 200 on every canonical service path.

• GET /mcp exposes eight tools.

• Unpaid production calls return HTTP 402 with the correct absolute resource URL and fee.

• A valid paid call settles through the OKX facilitator before the result is used for marketplace review.

Safety Boundary

The suite is read-only. It does not sign transactions, execute swaps, guarantee outcomes, or present results as financial advice. Risk scores summarize available evidence and always retain source and coverage information.