io.github.naur9n/arbitrum-transaction-preflight

Arbitrum Transaction Preflight

Paid transaction simulation and risk reports for wallets, bots, and AI agents. Before a transaction is signed, the API checks whether it simulates successfully, estimates gas, detects token/NFT approvals, inspects the target, and returns a machine-readable risk score.

Production API: https://arbitrum-mpp-transaction-preflight-production.up.railway.app

Product and pricing

• Network: Arbitrum One (42161)
• Asset: native USDC (0xaf88d065e77c8cC2239327C5EDb3A432268e5831)
• Launch price: 0.10 USDC per report (100000 raw USDC units)
• Primary payment channel: MPP with EIP-3009
• Optional distribution channel: x402 with Coinbase CDP/Bazaar
• Agent interface: MCP stdio server that pays the MPP endpoint with the caller's wallet

The service never asks for a transaction-signing wallet. The example MPP/MCP clients use a separate low-value payer key only to authorize the API payment.

Discovery endpoints

The hosted service exposes free discovery metadata:

• GET / — product, network, price, and endpoint summary
• GET /health — health check
• GET /openapi.json — MPP-aware OpenAPI 3.1 discovery document
• GET /llms.txt — concise instructions for AI agents
• GET /.well-known/agent.json — agent/service metadata

MPP clients call:

POST /v1/preflight

When x402 is enabled, x402 clients call:

POST /x402/v1/preflight

Request and report

{
  "from": "0x0000000000000000000000000000000000000001",
  "to": "0x0000000000000000000000000000000000000002",
  "data": "0x",
  "valueEth": "0"
}

from and to are required. data defaults to 0x. Use either valueEth or valueWei for native value. A successful paid response contains:

• call simulation success/revert details;
• gas estimate, gas price, and estimated ETH cost;
• EOA/contract target inspection;
• ERC-20 approve and NFT setApprovalForAll detection;
• weighted risk score and warnings;
• block number and check timestamp.

Automated simulation and heuristics reduce risk but are not a guarantee of safety.

Run locally

Requirements: Node.js 22+ and a dedicated server wallet. On mainnet, the server wallet needs a small Arbitrum One ETH balance for MPP settlement gas.

npm install
cp .env.example .env
npm run server

Minimum production configuration:

SERVER_PRIVATE_KEY=0x...
CHAIN_ID=42161
ARBITRUM_RPC=https://arb1.arbitrum.io/rpc
PRICE_RAW_USDC=100000
ENABLE_FREE_DEMO=false
SERVER_URL=https://arbitrum-mpp-transaction-preflight-production.up.railway.app

Never commit .env or expose SERVER_PRIVATE_KEY.

MPP client

The included client performs the complete 402 -> authorization -> retry -> receipt flow:

CLIENT_PRIVATE_KEY=0x...
TARGET_ADDRESS=0x...
SERVER_URL=https://arbitrum-mpp-transaction-preflight-production.up.railway.app
CHAIN_ID=42161

npm run client

The payer needs native USDC on Arbitrum One. It does not need ETH for the MPP payment; the merchant settles the signed EIP-3009 authorization.

MCP integration

The MCP server exposes check_arbitrum_transaction. It uses the caller's dedicated CLIENT_PRIVATE_KEY to pay the hosted MPP API, so each tool call produces API revenue instead of bypassing payment.

npm run mcp

After the npm package is published, MCP hosts can run:

{
  "mcpServers": {
    "arbitrum-preflight": {
      "command": "npx",
      "args": ["-y", "arbitrum-mpp-transaction-preflight"],
      "env": {
        "CLIENT_PRIVATE_KEY": "0x...",
        "SERVER_URL": "https://arbitrum-mpp-transaction-preflight-production.up.railway.app",
        "CHAIN_ID": "42161"
      }
    }
  }
}

Use a dedicated low-value payer wallet. Never reuse a valuable wallet key.

Enable x402 and Bazaar

Production x402 settlement on Arbitrum uses Coinbase's CDP facilitator. Create a CDP project and add these Railway variables:

ENABLE_X402=true
CDP_API_KEY_ID=...
CDP_API_KEY_SECRET=...

The server then exposes POST /x402/v1/preflight with Bazaar discovery metadata. MPP remains available at POST /v1/preflight; the two payment channels share the same analysis engine and merchant address.

Development checks

npm run typecheck
npm run build
npm pack --dry-run

Set ENABLE_FREE_DEMO=true only for local development to expose POST /demo/preflight without payment. Never enable it in production.

Publishing surfaces

The repository includes server.json and npm metadata for the official MCP Registry. Release order:

1. deploy this version to Railway;
2. publish arbitrum-mpp-transaction-preflight to npm;
3. publish server.json with mcp-publisher;
4. enable CDP x402 to become eligible for Bazaar indexing;
5. submit the live MPP endpoint to the MPP services catalog.

Official Arbitrum MPP guide: https://docs.arbitrum.io/build-decentralized-apps/machine-payments-protocol