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 authentication

HTTP and JSON-RPC

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"}'

WebSocket

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.

gRPC

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 authentication

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.

Protect the key in telemetry

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.