Nomatica AI

Appearance

Ethereum Gateway ​

Last updated: 2026-07-26

A stateless, multi-network Ethereum RPC gateway running on Cloudflare's edge. The gateway is a thin proxy with edge caching, per-IP rate limiting, and a curated token registry for Nomatica's products. It is provider-agnostic — the client SDK supplies the upstream RPC URL on every request, so no third-party provider is hardcoded in the worker config.

Base URL ​

EnvironmentURLStatus
Productionhttps://eth.colorfulmoves.comlive
Previewhttps://nomatica-ethereum-gateway.nomatica.workers.devlive

All paths below are relative to the base URL.

Networks ​

The gateway supports the following chains out of the box. The chainId column is the canonical EIP-155 chain id.

NetworkchainIdSymbol
mainnet1ETH
sepolia11155111SEP
arbitrum42161ETH
optimism10ETH
polygon137MATIC
base8453ETH
avalanche43114AVAX
bsc56BNB
zksync324ETH

Endpoints ​

GET / (or /gateway) ​

Service discovery. Returns the gateway version, the list of supported networks, the token registry, and a one-line summary of every endpoint. No RPC required.

bash
curl https://eth.colorfulmoves.com/

GET /health ​

Lightweight liveness probe. Returns {status, latency_ms, block_number} when a working RPC is supplied via ?rpcUrl=.... Returns 200 with a degraded payload if no RPC is supplied (the gateway is still reachable, but the chain-side health check is skipped).

bash
curl "https://eth.colorfulmoves.com/health?rpcUrl=https://eth.llamarpc.com"

POST /v1/{network} — JSON-RPC proxy ​

Stateless JSON-RPC 2.0 proxy. The body is forwarded as-is to the RPC URL passed in ?rpcUrl=.... Cached for 5 seconds per (method, params) tuple (cache TTL is configurable via the CACHE_TTL_SECONDS constant in the worker).

bash
curl -X POST "https://eth.colorfulmoves.com/v1/mainnet?rpcUrl=https://eth.llamarpc.com" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Allowed methods are whitelisted (read-only JSON-RPC by default; write methods require a separate WRITE_METHODS allowlist that is currently empty in production).

GET /v1/{network}/block/latest ​

Returns the latest block number. Requires ?rpcUrl=....

bash
curl "https://eth.colorfulmoves.com/v1/mainnet/block/latest?rpcUrl=https://eth.llamarpc.com"
# → { "network": "mainnet", "block_number": "0x1a2b3c", "block_number_decimal": 1715100 }

GET /v1/{network}/balance/{address} ​

Returns the native-token balance (ETH, MATIC, BNB, …) for address.

bash
curl "https://eth.colorfulmoves.com/v1/mainnet/balance/0xd8da6bf26964af9d7eed9e03e53415d37aa96045?rpcUrl=https://eth.llamarpc.com"
# → { "address": "0xd8da…045", "balance_wei": "1234567890000000000", "balance": "1.23456789" }

GET /v1/{network}/tokens ​

Returns the token registry for network — the list of supported symbols plus their address, decimals, isNative, and priceFeed fields. No RPC required (data is baked into the worker at build time).

bash
curl https://eth.colorfulmoves.com/v1/mainnet/tokens
# → { "network": "mainnet", "chain_id": 1, "tokens": { "ETH": {...}, "USDC": {...}, ... } }

GET /v1/{network}/token/{symbol}/info ​

Returns the metadata for one token. No RPC required.

bash
curl https://eth.colorfulmoves.com/v1/mainnet/token/USDC/info
# → { "network": "mainnet", "symbol": "USDC", "address": "0xA0b8…B48", "decimals": 6, "isNative": false, "priceFeed": "0x8fFf…18f6" }

GET /v1/{network}/token/{symbol}/balance/{address} ​

Returns the ERC-20 balance of symbol for address. Requires ?rpcUrl=....

bash
curl "https://eth.colorfulmoves.com/v1/mainnet/token/USDC/balance/0xd8da6bf26964af9d7eed9e03e53415d37aa96045?rpcUrl=https://eth.llamarpc.com"
# → { "symbol": "USDC", "address": "0xd8da…045", "balance_raw": "1000000", "balance": "1.000000" }

GET /v1/{network}/price/{symbol} ​

Returns the Chainlink price-feed value for symbol in USD. The token must have a priceFeed field in the registry. Requires ?rpcUrl=....

bash
curl "https://eth.colorfulmoves.com/v1/mainnet/price/ETH?rpcUrl=https://eth.llamarpc.com"
# → { "symbol": "ETH", "price_usd": 3542.18, "decimals": 8, "round_id": "0x…" }

GET /v1/{network}/portfolio/{address} ​

Returns the multi-token portfolio for address — every supported token's balance + USD value, computed by walking the registry. Requires ?rpcUrl=.... Cached for 30 seconds.

bash
curl "https://eth.colorfulmoves.com/v1/mainnet/portfolio/0xd8da6bf26964af9d7eed9e03e53415d37aa96045?rpcUrl=https://eth.llamarpc.com"
# → { "address": "0xd8da…045", "total_usd": 12450.00, "tokens": [ { "symbol": "ETH", "balance": "1.5", "value_usd": 5313.27 }, ... ] }

GET /v1/{network}/contracts ​

Returns the Nomatica V2 contract addresses for network. No RPC required.

bash
curl https://eth.colorfulmoves.com/v1/mainnet/contracts
# → { "network": "mainnet", "contracts": { "NOMAV2": "0x…", "LENDING_POOL": "0x…", ... } }

POST /v1/{network}/batch ​

Batched JSON-RPC. Body is a JSON array of JSON-RPC requests; the response is the corresponding array of responses. Requires ?rpcUrl=.... Cached per element.

bash
curl -X POST "https://eth.colorfulmoves.com/v1/mainnet/batch?rpcUrl=https://eth.llamarpc.com" \
  -H "Content-Type: application/json" \
  -d '[
    {"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]},
    {"jsonrpc":"2.0","id":2,"method":"eth_gasPrice","params":[]}
  ]'

CORS ​

The gateway allows cross-origin requests from:

  • https://colorfulmoves.com (and www. variant)
  • https://api.colorfulmoves.com
  • https://gateway.colorfulmoves.com
  • http://localhost:3000, :5173, :3030 (dev)

Add your origin to the ALLOWED_ORIGINS array in ethereum-gateway-worker.js if you need access from another domain.

Rate limits ​

300 requests per IP per 60-second window. The counter lives in the RATE_LIMITS KV namespace and is enforced on the read path (/v1/*); the discovery endpoints (/, /health, /v1/{network}/tokens, /v1/{network}/contracts, /v1/{network}/token/{symbol}/info) are unmetered. Hitting the limit returns 429 Too Many Requests with a Retry-After header.

Caching ​

Successful read responses are cached in the SESSION_CACHE KV namespace for 5 seconds (configurable via CACHE_TTL_SECONDS). Cache key is cache:{method}:{sha256(body)}. Cache writes are best-effort — the gateway never fails a request because the cache write failed.

Provider-agnostic design ​

The worker does not hardcode any RPC endpoint. Clients pass the upstream RPC URL on every request via the ?rpcUrl= query parameter. This means:

  • The Nomatica team is not on the hook for the upstream provider's SLA — pick whatever provider you trust.
  • You can use the gateway as a thin shim over your own Ethereum node (e.g. an Erigon box behind a Cloudflare Tunnel) without code changes.
  • Provider selection is the SDK's job, not the gateway's. The reference SDK picks the lowest-latency provider per request using the gateway.colorfulmoves.com routing table.

Observability ​

Every request emits a cf-ray header and a server-timing header (cfEdge;dur=...,cfOrigin;dur=...,cfWorker;dur=...). Successful requests are recorded in the D1 usage table for billing and abuse-detection purposes. Aggregate metrics (request count, error rate, p50/p95/p99 latency) are available at the gateway's /metrics endpoint if enabled by the operator.

Versioning ​

The gateway version is returned in the GET / response under version. The current production version is 2.5.0. Breaking changes (e.g. a new required query parameter, a removed endpoint) will bump the major version. The gateway follows semver: a minor bump may add a new optional field to a response; a patch bump is bug-fix only.

Released under the Apache 2.0 License.

Copyright © 2026 Nomatica Security Team