Providers & credits

Behind the single endpoint sit the providers a web3 project reaches for: chain reads, indexing, prices, and cross-chain routing, across every network you deploy to. The Gateway doesn't reshape their APIs; it authenticates, routes, caches, and meters in front of each one.

The providers

Each provider exposes its own routes and parameters after its path segment; consult that provider's own API reference for specifics.

Networks (Alchemy)

RPC calls name the network as the segment after alchemy. Supported networks include:

• Ethereum: eth-mainnet, eth-sepolia, eth-holesky
• Base: base-mainnet, base-sepolia
• Arbitrum: arb-mainnet, arb-sepolia
• Optimism: opt-mainnet, opt-sepolia
• Polygon: polygon-mainnet, polygon-amoy
• BNB Chain: bnb-mainnet, bnb-testnet
• Robinhood Chain: robinhood-mainnet, robinhood-testnet
• Arc: arc-mainnet, arc-testnet
• Solana: solana-mainnet, solana-devnet
• …plus zkSync and Starknet (mainnet + testnet)

Subgraph registry

The Graph exposes a free, no-auth helper so agents can discover canonical subgraphs instead of hardcoding IDs:

GET ${MODUS_GATEWAY_URL}/api/gw/thegraph/registry

It returns curated subgraph IDs (Uniswap V3 on Ethereum and Base, ENS, and more). This route is free; it doesn't touch your credits.

Credits

Every call runs through the Gateway, and usage draws on your Modus credits, metered by what you actually consume. There are no per-provider dashboards or invoices to reconcile. The Gateway is the one place your project's external usage is counted, and each response tells you the cost via the x-modus-cost-cents header.

You're not charged when a call fails for reasons outside your control: upstream 5xx errors and rate-limit (429) responses are free. Cache hits, by contrast, are billed at the normal price — a cached response still costs what the underlying provider call costs.

Your remaining credits show in the dashboard header, the same pool that covers prompts across the chapters. See Credits & billing.

Bring your own provider key

If you'd rather run a provider on your own account, supply your upstream key for it (your own Alchemy key, for example). While that key is set:

• The Gateway routes those calls through your account instead of the shared pool.
• They bill as zero Modus credits; you pay the provider directly.
• Everything else stays the same: one endpoint, one auth header, the same metering visibility.

It's one key per provider, encrypted at rest, and you can remove it anytime to fall back to the managed pool. Connect a provider key from the Gateway providers section of the Integrations page.

Gateway keys

Your project's gateway key is issued automatically, but you can also mint keys yourself from Settings: name them, cap their monthly spend, restrict them to specific origins and providers, and revoke them anytime. A key's value is shown once at creation; after that only its last characters appear.

Limits you might hit

The Gateway protects shared providers with rate limits. If you burst too fast you'll get a 429 with a Retry-After header; back off and retry. Heavily-used providers also have fair-use concurrency queues; under sustained load a request may wait briefly or return 503, which is also safe to retry.

Heavy and real-time workloads

The pooled Gateway is built for the reads, prices, and routing a typical dApp makes. Products that hammer the chain continuously (snipers, copy-traders, high-frequency polling, large-scale indexing) share those pooled limits with every other Modus user, so steady high throughput on the pool is not guaranteed, and usage draws on your credits the whole time.

Two rules of thumb:

• Sustained bots belong on your own key. Bring your own provider key and those calls run on your account and your limits, at zero Modus credits. Modus wires it in for you; see Bring your own provider key. Prototype on the pool, switch before you run for real.
• Provider websockets and webhooks don't go through the Gateway. Those need a direct connection to the provider, on your own key. (The Gateway's own live price stream, served over SSE, is rolling out.)