API Authentication

Dwellir accepts X-Api-Key or an API key in the endpoint URL path for HTTP and WebSocket connections. gRPC clients must use lowercase x-api-key request metadata.

Use the header when your tracing or logging system records request URLs. Use the URL path when your client cannot set custom headers.

Header authenticationCopy Anchor Link

HTTP and JSON-RPCCopy Anchor Link

Set the X-Api-Key header on each request:

export DWELLIR_API_KEY="YOUR_API_KEY"

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${DWELLIR_API_KEY}" \
  https://api-ethereum-mainnet.n.dwellir.com \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

The header also works with HTTP APIs that use paths after the endpoint host. This example calls the Hyperliquid Info API:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${DWELLIR_API_KEY}" \
  https://api-hyperliquid-mainnet.n.dwellir.com/info \
  -d '{"type":"perpDexs"}'

WebSocketCopy Anchor Link

Send X-Api-Key during the WebSocket upgrade request. This Node.js example uses the ws package:

import WebSocket from 'ws';

const ws = new WebSocket('wss://api-ethereum-mainnet.n.dwellir.com', {
  headers: {
    'X-Api-Key': process.env.DWELLIR_API_KEY,
  },
});

The browser WebSocket API cannot set custom headers. For production browser applications, connect through a backend that adds the header.

Direct URL path authentication exposes the key to every browser user. If you require direct browser access, create a separate key, set a strict quota, and rotate it when needed.

gRPCCopy Anchor Link

Send the API key as lowercase x-api-key request metadata:

x-api-key: YOUR_API_KEY

See the Sui gRPC authentication examples for TypeScript, Python, and Go clients.

URL path authenticationCopy Anchor Link

Add the API key after the endpoint host when your client cannot set custom headers:

https://api-{network}.n.dwellir.com/YOUR_API_KEY
wss://api-{network}.n.dwellir.com/YOUR_API_KEY

Both forms use the same API key, quotas, and usage accounting.

Do not place a reusable server key in browser code. Browser users can read any key sent in the URL.

Restrict a key by source IPCopy Anchor Link

Authentication proves a request carries a valid key. It does not prove the request came from you. Add IP whitelisting so the key only works from source addresses you own.

Manage whitelists in the IP Whitelisting tab. A key with no enabled whitelist is unrestricted by IP. A restricted key denies everything else with HTTP 403 before the request reaches a node, so blocked traffic costs nothing.

Whitelisting suits server-side workloads with stable egress addresses. It cannot restrict browser or mobile clients. See When to use IP whitelisting for that split.

Protect the key in telemetryCopy Anchor Link

Header authentication prevents the API key from appearing in the request URL. It does not hide the key from tools that record request headers.

Configure your logs, traces, reverse proxies, and error reports to redact X-Api-Key. Store the key in an environment variable or secret manager. Do not commit it to source control.