How ENS BTC Address Works: Everything You Need to Know

Introduction: The Cross-Chain Identity Problem

The Ethereum Name Service (ENS) was originally designed to resolve human-readable names (e.g., alice.eth) to Ethereum addresses, smart contract addresses, and content hashes. However, as the blockchain ecosystem expanded, a critical demand emerged: users wanted a single ENS name to map to addresses on multiple blockchains, including Bitcoin. The solution—mapping an ENS name to a Bitcoin address—requires a fundamentally different architecture because Bitcoin does not support the same on-chain scripting or naming infrastructure as Ethereum. This article explains the precise technical mechanism by which ENS resolves BTC addresses, the underlying data structures, and the practical implications for developers and power users.

To understand this, we must first distinguish between two resolution modes: direct on-chain resolution (used for Ethereum addresses) and off-chain resolution (used for non-EVM chains like Bitcoin). ENS employs a hybrid approach called the ENSIP-12 standard (ERC-3668, or "CCIP-Read") to fetch BTC address data from off-chain storage without incurring high gas costs or requiring Bitcoin to run a smart contract.

1. The Core Data Structure: Text Records and the BTC Key

ENS names store arbitrary key-value pairs as text records. The ENS registry on Ethereum mainnet holds a resolver contract for each domain, which can expose a text() function. Bitcoin addresses are stored under the key btc (with the legacy alias bitcoin). When you set a BTC address for your ENS name, you are essentially writing a text record with the key "btc" and the value being the Bitcoin address string (e.g., 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa). This record is stored either directly in the resolver contract (when using a standard public resolver) or—more commonly—in an off-chain gateway.

Here is how a typical resolution flow works for BTC:

1. Client query: A dApp or wallet calls the ENS resolver's text(bytes32 node, string memory key) function with the namehash of alice.eth and key "btc".
2. On-chain lookup: The resolver returns a result if the record exists on-chain. However, for large or multi-address profiles, the resolver may instead return a OffchainLookup error (per ERC-3668) with a URL pointing to an off-chain HTTP gateway.
3. Off-chain fetch: The client fetches the BTC address from the gateway (e.g., https://gateway.ens.domains/addr/1337/alice.eth/btc), which returns a signed EIP-712 message proving the data's authenticity.
4. Verification: The client verifies the signature against the resolver's public key configured in the ENS registry. If valid, the BTC address is accepted.

2. Why Off-Chain Resolution Is Necessary for Bitcoin

Bitcoin cannot directly interact with the ENS smart contracts on Ethereum. Writing a BTC address to the ENS registry on Ethereum would require an oracle or a bridge, which introduces trust assumptions. The off-chain approach using CCIP-Read eliminates the need for such bridges while preserving data integrity. A major advantage is cost: storing a 34-character Bitcoin address on Ethereum L1 costs approximately 50,000 gas (roughly $2-5 at current ETH prices). Storing the same data off-chain reduces this to near zero, with the gateway charging minimal fees for signature generation.

This design also enables a crucial security property: the BTC address can be updated without paying Ethereum gas fees. The domain owner simply updates the record in the off-chain database, and the next query returns the new address. However, this introduces a reliance on the gateway's availability and honesty. To mitigate this, modern ENS tooling (like the ENS App) allows users to pin records to multiple gateways or use a personal gateway. For an in-depth discussion of wallet recovery mechanisms that leverage this off-chain model, explore ENS social recovery patterns that combine multiple signers to authorize address changes.

3. Setting a BTC Address on Your ENS Name

The technical process of associating a BTC address with an ENS name involves three steps: obtaining the namehash, calling the resolver's setText() function, and (optionally) configuring the off-chain gateway. Below is a concrete workflow using the ENS JS library:

const ethers = require('ethers');
const { ENS } = require('@ensdomains/ensjs');

const provider = new ethers.providers.JsonRpcProvider('https://mainnet.infura.io/...');
const signer = new ethers.Wallet('0xPRIVATE_KEY', provider);
const ens = new ENS({ provider, signer });

await ens.setText('alice.eth', 'btc', 'bc1qar0srrr0x0yzwm8x9k9y8z0x0yzwm8x9k9y8z0');

This snippet writes the Bech32 address to the resolver. The transaction cost is determined by the gas price at the time: currently around 120,000 gas for a text record update. After the transaction confirms, any query for alice.eth with key "btc" will return the Bitcoin address. However, note that many wallets (e.g., MetaMask, Rainbow) do not natively support Bitcoin address resolution because they only check the default addr key (which expects an Ethereum address). To integrate BTC resolution into a dApp, developers must explicitly call the text() function with the correct key.

4. Cross-Chain Resolution Standards and Compatibility

The ENS ecosystem has standardized the BTC address key through ENSIP-9 and EIP-2304. The Bitcoin address is stored as a string, not a hex-encoded byte array. This means that any Bitcoin address format is supported: legacy (P2PKH), nested SegWit (P2SH-P2WPKH), native SegWit (Bech32), and Taproot (Bech32m). The resolver does not validate the address format; it simply returns the string as stored. It is the client's responsibility to parse and validate the Bitcoin address.

For multi-address resolution, the same name can hold multiple records: btc, eth, bnb, ltc, etc. This enables a unified cross-chain identity. However, the cost of storing many records on-chain becomes prohibitive. Therefore, power users often use the "ENS Public Resolver 2" with off-chain storage. The off-chain gateway can serve hundreds of address records for a single domain at virtually no on-chain cost. If you are building a cross-chain oracle that needs to query multiple ENS-managed Bitcoin addresses, the Crypto Domain Oracle Integration approach provides a validated data pipeline with signed responses.

5. Practical Use Cases and Limitations

The primary use case for ENS BTC address resolution is simplifying Bitcoin payments. Instead of asking a user to copy-paste a 34-character Bitcoin address, you can ask for their ENS name and resolve the BTC record programmatically. This is increasingly adopted by Bitcoin wallet interfaces, donation pages, and NFT marketplaces that support multi-currency checkouts.

However, there are notable limitations:

• No Bitcoin-native verification: The BTC address is stored on Ethereum, not on Bitcoin. There is no way to verify on Bitcoin that the ENS name controls the address. This creates a trust model: users trust that the ENS resolver contract (or off-chain gateway) is honest.
• Gas costs for updates: While off-chain storage reduces read costs, updating the BTC record still requires an Ethereum transaction (unless using a gasless meta-transaction relay).
• Client support: As of 2025, only a handful of wallets and tools automatically resolve BTC records. Most require explicit calls to the text() function.
• Key collision risk: Using the key btc is standard, but legacy implementations used bitcoin. Developers must check both keys for compatibility.

For enterprise deployments, caching these BTC records is recommended. A typical pattern is to query the ENS resolver once and store the result in a local database for 24 hours, refreshing only when the name's text records change (monitored via the TextChanged event on the resolver). This reduces dependency on Ethereum RPC availability.

Conclusion: The Future of Multi-Chain Naming

ENS BTC address resolution is a critical bridge between the Ethereum and Bitcoin ecosystems. By leveraging off-chain data gateways and standardized text records, ENS enables a single name to serve as a universal blockchain identifier. The technology is mature enough for production use, but requires careful handling of trust assumptions and client-side validation. As cross-chain interoperability matures, expect ENS to support not just addresses but also unsigned Bitcoin scripts and LNURLs for Lightning Network payments. Developers building wallet infrastructure or payment systems should prioritize supporting the btc text record as a standard way to accept Bitcoin payments via ENS names.