Aptos API Authentication

Every Dwellir Aptos endpoint authenticates with the same API key from your dashboard. There is no separate streaming credential and no per-service token to provision.

What changes between services is where the key goes.

REST and GraphQL

Both take the key as a path segment before /v1:

curl -X GET https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1 \
  -H "Accept: application/json"

curl -X POST https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"query { ledger_infos(limit: 1) { chain_id version } }"}'

Transaction Stream (gRPC)

The gRPC stream takes the key as metadata, matching how our Sui gRPC endpoints work. Do not append it to the endpoint as a path segment.

x-api-key: YOUR_API_KEY

Handling Auth Failures

A rejected key surfaces as UNAUTHENTICATED (gRPC status 16) on the stream, or 401 on REST and GraphQL:

import { status } from '@grpc/grpc-js';

stream.on('error', (error) => {
  if (error.code === status.UNAUTHENTICATED) {
    // Key is missing, wrong, or not provisioned for the stream.
    // Do not retry with backoff - this will not resolve on its own.
    return alertOperator(error.details);
  }

  scheduleReconnect();
});

Authentication failures are not transient. Retrying an invalid key burns your rate limit and delays the alert, so keep it off the reconnect path.

Do not confuse it with RESOURCE_EXHAUSTED (status 8), which means rate limiting rather than a bad key — and on Dwellir, rate limits are scoped per account, not per key.

Key Handling

• Keep keys server-side. A key embedded in a browser or mobile bundle is public. Proxy through a backend you control.
• Use environment variables or a secrets manager, never checked-in config.
• Use separate keys per environment so a staging mistake cannot exhaust production budget — though note that rate limits pool per account, so separate keys on one account still share a limit.
• Rotate through the dashboard and set per-key usage quotas at dashboard.dwellir.com/api-keys.
• Never log the key, including in gRPC metadata dumps while debugging.

Related Guides

• Transaction Stream Overview — service definition and metering
• Real-Time Streaming — tailing the head of chain
• Rate Limits — plan limits and per-account scope
• Sui gRPC Authentication — the same header on our Sui endpoints