Reverse Resolution

Resolve an address into its ENS reverse record on a given chain. Given 0xd8dA6BF…, returns vitalik.eth so you can show a name instead of a hex string. For the opposite direction (name → address and records), see Forward Resolution.

Endpoint

GET /ens/v2/reverse

Base URL: https://api.justaname.id

Quick start

The endpoint is free when you supply your own RPC URL via the rpcUrl query parameter. No API key required. Rate-limited to 30 requests per 60 seconds per IP.

curl "https://api.justaname.id/ens/v2/reverse?address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&coinType=60&rpcUrl=https://eth.drpc.org"

const url = new URL('https://api.justaname.id/ens/v2/reverse');
url.searchParams.append('address', '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045');
url.searchParams.set('coinType', '60');
url.searchParams.set('rpcUrl', process.env.RPC_URL!);

const res = await fetch(url);

To get the full profile in the same call, add records=true. The response then includes every record set on the resolved name (text records, addresses, contenthash) alongside it:

curl "https://api.justaname.id/ens/v2/reverse?address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&coinType=60&records=true&rpcUrl=https://eth.drpc.org"

The caller's RPC pays for the on-chain reads. JustaName performs the reverse lookup through the ENS Universal Resolver and falls back to its off-chain reverse-record store when no on-chain reverse record is set.

Autonomous clients without an RPC URL (AI agents, MCP servers, scripts) can pay per-request in USDC on Base instead of supplying rpcUrl. See Programmatic access without an RPC URL.

Parameters

Parameter	Type	Required	Description
address	string (repeatable)	Yes	Address to reverse-resolve. Repeat to batch up to 50 addresses (?address=0x…&address=0x…). Plain (0x…) or interop-formatted — see Interop addresses.
coinType	number	Conditional	ENSIP-19 coinType — see coinType reference. Required for plain addresses; optional when every address in the batch carries an interop suffix.
rpcUrl	string	See below	HTTPS RPC URL used to perform the on-chain resolution.
records	boolean	No	Default false. When true, fetches all records set on each resolved name (text records, addresses, contenthash) and returns them in the response. Applies to every address in a batch. Skipped for addresses with no reverse record (name: null).

Either rpcUrl must be present or the request must carry a valid payment header. Without either, the endpoint returns 402 with a payment challenge — see Programmatic access without an RPC URL.

Interop addresses

By default, the request-level coinType applies to every address in the batch. To override per-slot — for example, when batching addresses across different chains — append a chain suffix to the address:

Format	Effect
0xd8dA…6045 (with coinType=60)	Reverse on Ethereum
0xd8dA…6045@ethereum	Reverse on Ethereum (overrides coinType)
0xd8dA…6045@eip155:1	Reverse on Ethereum (overrides coinType)
0xbbb…@eip155:8453	Reverse on Base

Both the human-readable chain name and the CAIP-2 form (eip155:<chainId>) are accepted. The suffix is per-address, so a batch can mix suffixed and request-level-scoped slots:

?address=0xaaa…@eip155:1&address=0xbbb…@eip155:8453&address=0xccc…&coinType=10&rpcUrl=...

When every address in the batch carries a suffix, the request-level coinType becomes optional.

RPC URL requirements

Same as Forward Resolution: HTTPS only, no private/loopback/link-local hosts, no embedded credentials.

coinType reference

ENSIP-19 coinTypes follow the formula 0x80000000 | chainId for EVM L2 primaries. Ethereum mainnet is the exception (60).

Chain	Decimal	Hex
Ethereum mainnet	60	0x3c
Optimism	2147483658	0x8000000a
Base	2147492837	0x80002105
Arbitrum One	2147525809	0x8000a4b1
ENSIP-19 default (step-2 fallback)	2147483648	0x80000000

Response

Returns a single object when one address is requested, or an array of slot-level objects (with per-slot error) when multiple are requested.

type ReverseResponse = {
  statusCode: number;
  result: {
    data: ReverseResult | ReverseBatchResult[] | null;
    error: string | null;
  };
};

type ReverseResult = {
  address: string;
  name: string | null;
  coinType: number;
  viaUniversalResolver: boolean;
};

type ReverseBatchResult = {
  address: string;
  name: string | null;
  coinType: number | null;
  viaUniversalResolver: boolean;
  error: string | null;
};

Single address

{
  "statusCode": 200,
  "result": {
    "data": {
      "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "name": "vitalik.eth",
      "coinType": 60,
      "viaUniversalResolver": true
    },
    "error": null
  }
}

Batch

{
  "statusCode": 200,
  "result": {
    "data": [
      {
        "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
        "name": "vitalik.eth",
        "coinType": 60,
        "viaUniversalResolver": true,
        "error": null
      },
      {
        "address": "0xb965a5f3a0fc18d84e68883ccad508445a7917a8",
        "name": null,
        "coinType": null,
        "viaUniversalResolver": true,
        "error": "coinType is required for plain addresses"
      }
    ],
    "error": null
  }
}

Behavior

For each address, a 3-step fallback chain is walked. The first hit wins:

1. On-chain reverse lookup with the supplied coinType (or the coinType derived from the interop suffix).

2. On-chain reverse lookup with the ENSIP-19 default coinType (0x80000000) — covers L2 names with a chain-agnostic reverse record.

3. JustaName off-chain reverse-record store.

Other notes:

• viaUniversalResolver: true → resolved on-chain (step 1 or 2). viaUniversalResolver: false → resolved from the JustaName off-chain store (step 3).

• name: null is a normal outcome (most addresses do not have a reverse record set), not a failure.

• In batch mode, slot failures are localized: the slot returns name: null with a populated error, and the rest of the batch succeeds.

• For batch slots that fail preflight (malformed interop suffix, unsupported chain label, missing coinType for a plain address), coinType is null.

Labelling a multi-chain list

const inputs = [
  '0xaaa...@eip155:1',     // mainnet
  '0xbbb...@eip155:8453',  // Base
  '0xccc...@eip155:10',    // Optimism
];

const url = new URL('https://api.justaname.id/ens/v2/reverse');
inputs.forEach((a) => url.searchParams.append('address', a));
url.searchParams.set('rpcUrl', process.env.RPC_URL!);

const res = await fetch(url);

const { result } = (await res.json()) as ReverseResponse;
if (result.error) throw new Error(result.error);

const items = result.data as ReverseBatchResult[];
for (const item of items) {
  if (item.error) {
    console.warn(item.address, item.error);
    continue;
  }
  console.log(item.address, '→', item.name ?? '(no reverse record)');
}

Errors

Status	When
400	rpcUrl not HTTPS, has embedded credentials, or resolves to a private/loopback host.
400	address malformed (not 0x[40-hex] optionally followed by @<chain>).
400	address array empty or > 50 entries.
400	Single-address request with a plain address and no coinType.
400	Unknown chain label in the interop suffix.
429	Rate limit (30 req / 60 s per IP) exceeded. Body includes retryAfterSeconds.
502 / 504	RPC provider error or CCIP-Read gateway timeout.

Payment-related statuses (402, 503) are documented in the paid path section.

---

Programmatic access without an RPC URL

For clients that don't manage their own RPC infrastructure — AI agents, MCP servers, autonomous scripts — the endpoint accepts per-request payment in place of rpcUrl. The service performs the on-chain reads and charges the caller in USDC on Base.

Two protocols are accepted on the same route. Clients pick whichever fits their stack:

• x402 v2 — Coinbase's HTTP-payment protocol. See x402.org.

• MPP-charge — IETF Internet-Draft draft-httpauth-payment-00 with EVM method draft-evm-charge-00. Co-authored by Tempo Labs and Stripe.

Both protocols settle identically — a signed EIP-3009 transferWithAuthorization submitted by a facilitator on Base. They differ only in HTTP envelope.

Chain	Base mainnet (eip155:8453)
Asset	USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
Price	1000 base units per request (0.001 USDC at 6 decimals)

402 challenge

A request without rpcUrl and without a payment header receives both challenges in one response. The headers are disjoint, so they coexist:

HTTP/1.1 402 Payment Required
Content-Type: application/json
PAYMENT-REQUIRED: <base64 JSON — x402 v2 challenge>
WWW-Authenticate: Payment id="<uuid>", realm="api.justaname.id", method="evm", intent="charge", request="<base64url-nopad JSON — MPP challenge>"

Decoded PAYMENT-REQUIRED (x402 v2):

{
  "x402Version": 2,
  "resource": {
    "url": "https://api.justaname.id/ens/v2/reverse?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&coinType=60",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "1000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x...",
      "maxTimeoutSeconds": 60
    }
  ],
  "extensions": { "bazaar": { "info": "...", "schema": "..." } },
  "error": "PAYMENT-SIGNATURE header is required"
}

Decoded WWW-Authenticate request= (MPP draft-evm-charge-00):

{
  "network": "eip155:8453",
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "1000",
  "recipient": "0x...",
  "credentialTypes": ["eip3009"]
}

Paying

Sign an EIP-3009 transferWithAuthorization against the USDC contract on Base (e.g. viem's signTypedData with primaryType: "TransferWithAuthorization" and a fresh 32-byte nonce). Wrap the signed message in either envelope and retry the request:

Scheme	Request header	Receipt header (on 200)
x402 v2	PAYMENT-SIGNATURE: <base64 JSON>	PAYMENT-RESPONSE: <base64 JSON>
MPP-charge	Authorization: Payment <base64url-nopad JSON>	Payment-Receipt: <base64url-nopad JSON>

The facilitator submits the on-chain tx and pays gas — the payer only needs USDC, not ETH.

Idempotency, replay, validity

• Set Idempotency-Key: <uuid> on every retry. Without it, each retry is a fresh payment.

• (nonce, recipient) is locked in a 5-minute LRU. Always sign with a fresh random nonce.

• validBefore should be ~10 min from now(). Longer windows risk re-sending stale signatures past expiry.

• A retriable failure (facilitator transient error) returns 503 + Retry-After. Repeat the same request.

• A non-retriable failure (malformed payload, replay, network/asset mismatch) returns a fresh 402 with the reason in the challenge.

Discovery

• GET /ens/v2/pricing (free) — JSON list of paid routes: { path, method, schemes, amount, asset, network, recipient }.

• GET /.well-known/x402.json (free) — x402 manifest (services[] + accepts[]) for catalog crawlers (Bazaar, x402scan).

• GET /openapi.json — OpenAPI document. Each paid operation carries x-payment-info: { offers: [{ amount, currency, description, intent, method }] } per draft-payment-discovery-00.

Payment-path errors

Status	When
402	Request lacks rpcUrl and no payment header was supplied. PAYMENT-REQUIRED and WWW-Authenticate carry the challenge.
402	Payment proof was malformed, replayed, expired, or targeted the wrong network/asset.
503	Facilitator transient error during verify/settle. Retry-After set; repeat the same request.