Modus Gateway

Using the Gateway

Base URL, auth, the request pattern, response headers, and switching providers.

2 min read · 5 sections

Every provider is reached through one base URL and one bearer key. The provider's name is a path segment; the rest of the path is whatever that provider expects. The auth header never changes, so Alchemy, Etherscan, The Graph, and the rest all work the same way.

The pattern

Point requests at the Gateway and authenticate with your gateway key:

Text

${MODUS_GATEWAY_URL}/api/gw/{provider}/{provider-path}
Authorization: Bearer ${MODUS_GATEWAY_KEY}

{provider} is one of alchemy, etherscan, blockscout, thegraph, graph-tokens, lifi, enso, mobula, defillama — plus the unified swap namespace. Everything after it is passed through to that provider, so the shape of {provider-path} depends on which service you're calling.

Example

Reading wallet activity on Ethereum through Alchemy (RPC providers take the network as the next segment):

Text

POST ${MODUS_GATEWAY_URL}/api/gw/alchemy/eth-mainnet/v2
Authorization: Bearer ${MODUS_GATEWAY_KEY}

Calling a different provider is just a different path; the auth header stays the same:

Text

GET ${MODUS_GATEWAY_URL}/api/gw/etherscan/api?module=contract&action=getabi&address=0x...
Authorization: Bearer ${MODUS_GATEWAY_KEY}

See Providers & credits for each provider's path shape and the networks Alchemy supports.

The two values

Variable	What it is
`MODUS_GATEWAY_URL`	The Gateway base URL
`MODUS_GATEWAY_KEY`	Your project's gateway key

You don't create or manage these. Modus issues the key for your project and injects both values into your frontend's environment when you ship through the Deploy chapter, so deployed code can call the Gateway with no setup. Any agent you build gets the same access.

Response headers

Every proxied response carries a few x-modus-* headers so you can see what a call cost without leaving your code:

Header	Tells you
`x-modus-cost-cents`	What this request deducted, in cents (decimal — sub-cent charges like `0.15` are normal)
`x-modus-balance-cents`	Your remaining balance
`x-modus-cache`	`hit` or `miss` (on cacheable routes)
`x-modus-request-id`	The usage record ID, for support

Switching providers

Because the provider is just a path segment, changing which service backs a feature is a one-line edit. Moving a call from /api/gw/etherscan/... to /api/gw/alchemy/... keeps the same key, the same auth, the same code shape. Only the path changes.