Supported Chains & Wallets

Qeychain resolves a wallet from a single input: its address. You never pass a chain name or a network ID — Qeychain detects the chain from the address format, then routes the request to the right upstream data source (with automatic failover). This guide lists exactly which chains and address formats are supported, what each covers, and how validation and routing work.

All examples use the production base URL https://api.qeychain.xyz and the supported /api/v1 surface.

At a glance

Chain family	You pass	Detected as	What’s covered
EVM (Ethereum + many L1s/L2s)	a 0x… address	ethereum	Native coin + fungible (ERC‑20) tokens across all indexed EVM networks
Bitcoin	a bc1…, bc1p…, 1…, or 3… address	bitcoin	Native BTC balances and transfers
Solana	a base58 address	solana	Native SOL + fungible (SPL) tokens

Note

Coverage is fungible tokens and native coins only. NFTs are not indexed, and Bitcoin ordinals / inscriptions are filtered out. All values are reported in USD.

Authentication

Every /api/v1/wallets/* endpoint requires a Bearer access token, sent in the Authorization request header:

curl https://api.qeychain.xyz/api/v1/wallets/0xd8da6bf26964af9d7eed9e03e53415d37aa96045/dashboard \
  -H "Authorization: Bearer $QEYCHAIN_TOKEN"

A missing or invalid token returns 401 UNAUTHORIZED. See Authentication for how to obtain a token.

Supported chains

EVM (Ethereum and compatible networks)

Any address of the form 0x followed by 40 hexadecimal characters is treated as an EVM address. A single EVM address is resolved across every indexed EVM network in one call — you do not enumerate networks or repeat the request per chain. Indexed networks include (non‑exhaustive):

• Ethereum
• Polygon
• Arbitrum
• Optimism
• Base
• BNB Smart Chain
• Avalanche
• Gnosis
• Fantom
• Linea
• Scroll
• zkSync Era
• Blast
• Zora

Because the primary EVM data source is an aggregating passthrough, the list above grows as that source adds networks — an EVM address returns whatever networks it currently indexes for that wallet, without an API change on your side. EVM addresses are normalized to lowercase before use.

Bitcoin

Qeychain accepts all four common Bitcoin address encodings:

• Native SegWit (bech32) — starts with bc1
• Taproot (bech32m) — starts with bc1p
• Legacy P2PKH — starts with 1
• P2SH — starts with 3

Bitcoin coverage is native BTC only (balances and transfers). Inscription / ordinal transfers are intentionally skipped so they don’t pollute cost‑basis and holdings data. Bitcoin addresses are case‑sensitive and preserved as submitted.

Solana

Solana addresses are base58 strings, 32–44 characters long (the base58 alphabet excludes 0, O, I, and l). Coverage includes native SOL and fungible SPL tokens. Solana addresses are case‑sensitive.

Tip

For Solana, if the primary token‑balance source is degraded, Qeychain falls back to a native Solana RPC lookup so a valid wallet’s SOL balance still resolves instead of collapsing to zero. That fallback returns the native SOL position only — SPL token balances require the primary source.

Address formats

The table below shows the exact accepted patterns. An address must also be between 26 and 128 characters and must not contain injection‑style characters (<, >, quotes, control characters, .., or shell metacharacters), or it is rejected before chain detection.

Chain	Address type	Pattern	Example
EVM	Hex (Ethereum & all EVM)	^0x[a-fA-F0-9]{40}$	0xd8da6bf26964af9d7eed9e03e53415d37aa96045
Bitcoin	Legacy (P2PKH)	^1[a-km-zA-HJ-NP-Z1-9]{25,34}$	1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
Bitcoin	P2SH	^3[a-km-zA-HJ-NP-Z1-9]{25,34}$	3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy
Bitcoin	Native SegWit (bech32)	^bc1[a-z0-9]{39,59}$	bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq
Bitcoin	Taproot (bech32m)	^bc1p[a-z0-9]{58}$	bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr
Solana	Base58	^[1-9A-HJ-NP-Za-km-z]{32,44}$	DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK

Caution

Only the EVM, Bitcoin, and Solana families above are supported. Addresses that don’t match one of these patterns return 400 INVALID_ADDRESS. Chains outside these families are not routed to a data source and are not supported, even if the raw string looks address‑like.

How Qeychain picks the chain

Chain detection is purely format‑based, applied in this order:

1. Starts with 0x → EVM (ethereum)
2. Starts with bc1, or starts with 1/3 and is at least 26 characters → Bitcoin
3. Otherwise 32 characters or longer → Solana

Because detection is heuristic and prefix‑based, always submit a real, correctly formatted address. There is no chain parameter to override detection — the address is the single source of truth.

Data sources and failover

Qeychain aggregates several upstream indexers behind one API. You never select a provider; Qeychain routes by detected chain and fails over automatically. A per‑provider circuit breaker opens after 3 consecutive failures and re‑probes after 60 seconds.

Detected chain	Transactions (in order)	Positions / balances (in order)
EVM (ethereum)	primary EVM aggregator → EVM fallback indexer	primary EVM aggregator → positions fallback → EVM fallback indexer
Bitcoin	Bitcoin/Solana indexer	Bitcoin/Solana indexer
Solana	Bitcoin/Solana indexer	Bitcoin/Solana indexer → native Solana RPC (native SOL only)

If every configured source for a request fails, transaction endpoints return 502 (DATA_PROVIDER_ERROR, or PROVIDER_ENTITLEMENT_ERROR when the failure is a plan/quota issue rather than an outage). Positions are treated as non‑fatal and degrade to an empty list rather than erroring.

What’s included in results

• Fungible tokens and native coins only. No NFTs.
• USD valuation. Token prices come from the data source where available; native‑coin prices (BTC, SOL, ETH) are priced via CoinGecko and cached briefly server‑side.
• Low‑value token filtering (non‑EVM). For Bitcoin and Solana positions, tokens without meaningful liquidity (below roughly $5,000, unless flagged as high‑liquidity) are filtered out to suppress spam and scam tokens. Native assets are always kept.
• Bitcoin ordinals/inscriptions excluded from balances and history.

Submitting an address

Path‑based endpoints take the address as a URL segment. For example, to load a Solana wallet’s dashboard:

GET /api/v1/wallets/DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK/dashboard

curl "https://api.qeychain.xyz/api/v1/wallets/DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK/dashboard" \
  -H "Authorization: Bearer $QEYCHAIN_TOKEN"

Invalid address response

If the address fails validation, you get the standard v1 error envelope with a 400 status and code INVALID_ADDRESS:

{
  "success": false,
  "error": {
    "code": "INVALID_ADDRESS",
    "message": "Invalid wallet address. Supported: Ethereum (0x…), Bitcoin (bc1… / 1… / 3…), Solana.",
    "details": { "provided": "not-a-real-address" },
    "field": "address"
  },
  "meta": {
    "request_id": "b3f1c2a4-9d7e-4f0a-8c11-6a2e5d3b7f90",
    "timestamp": "2026-07-29T12:00:00Z",
    "version": "1.0.0"
  }
}

Notes and limits

• First call warms the wallet. For endpoints that require prior indexing, call /api/v1/wallets/{address}/dashboard first; a WALLET_NOT_FOUND (404) response tells you to do so.
• EVM addresses are lowercased, so checksummed and lowercase forms of the same address are treated identically.
• One address per path. Multi‑address (batch) resolution is not a recommended path today; document your integration around single‑wallet calls.