What remains private
Destination details and notes are returned only through an active wallet-authorized vault session. Private payment references are likewise stored in encrypted XDCID history and are not written into transaction calldata.
Developer documentation
Resolve human-readable .xdc names, integrate production APIs and contracts, and review clearly labelled preview tooling.
Private destination vault
The Exchange Address Book keeps an exchange name, your label, asset, network, deposit address, memo or tag, and private notes together. Each complete entry is encrypted at rest with authenticated AES-256-GCM encryption before it is stored. The database uses a wallet fingerprint to find the correct records and does not store the entry fields as readable columns.
Destination details and notes are returned only through an active wallet-authorized vault session. Private payment references are likewise stored in encrypted XDCID history and are not written into transaction calldata.
This is server-side encryption at rest, not end-to-end encryption. XDCID's protected server key is required to decrypt records after authorization. Public blockchain transfers still expose their normal on-chain sender, recipient, asset, amount, and transaction data.
Records are associated with the verified wallet and cannot be opened by merely knowing its address. The vault supports up to 100 saved destinations per wallet, and deleting an entry removes its encrypted record.
Wallet verification
Connect the wallet that owns the address book, then sign the one-time XDCID challenge. This is an off-chain message signature: it costs no gas, submits no transaction, moves no funds, and grants no token allowance.
Deposit safety
Confirm the asset, deposit network, address, and any memo or tag against the exchange deposit screen. A valid EVM address does not prove that the exchange accepts the selected asset on that network.
Selecting a saved destination applies its asset and network to both sides of a direct route and asks the connected wallet to switch to that network when necessary. Review the route before approving the transfer.
XDCID stores a memo or tag with the destination for reference, but Send cannot safely include it in the transfer yet. A saved entry that requires one is blocked instead of risking an uncredited exchange deposit.
Treat any exchange notice, address change, network change, or asset change as a new destination. Verify the latest deposit instructions before sending again, and retire entries that are no longer valid.
Payments
XDCID currently supports payments across five EVM mainnets. An XDCID name resolves to the destination address for the selected network; a saved exchange destination supplies its verified address, asset, and network directly.
| Network | Native asset | Chain ID | Direct payments |
|---|---|---|---|
| Ethereum | ETH | 1 | USDC and the network's native asset |
| XDC Network | XDC | 50 | USDC and the network's native asset |
| Polygon | POL | 137 | USDC and the network's native asset |
| Base | ETH | 8453 | USDC and the network's native asset |
| Arbitrum One | ETH | 42161 | USDC and the network's native asset |
Send USDC or the source network's native asset directly when the source and destination networks match. The payer approves one wallet transaction and pays that network's gas.
Send USDC between any two supported networks using Circle CCTP. Standard mode requires the payer to complete the source burn and destination mint. Automatic mode asks Circle to submit the destination mint and shows its forwarding cost plus the XDCID convenience fee before approval.
Native assets cannot be transferred cross-network. Memo/tag exchange deposits remain blocked, and XDCID does not convert assets or route payments through unsupported networks.
The dev environment mirrors these routes on Ethereum Sepolia, XDC Apothem, Polygon Amoy, Base Sepolia, and Arbitrum Sepolia. Always use test assets on dev and mainnet assets on production.
Public API
Public reads require no API key. Quote and Pay Link writes validate signed or wallet-bound input; they never accept a private key. Names are canonicalized to lowercase and may be supplied as a bare label or complete .xdc name.
/api/v1/names/{name}?years=1Returns the canonical name, owner, resolved address, availability, registration price, expiry, and profile records.
/api/v1/reverse/{address}Returns the verified primary XDCID name for a wallet address, or null when no current record exists.
/api/v1/addresses/{address}/namesReturns the verified primary ID and every active XDCID name currently owned by a wallet.
/api/v1/pricing/quote?product=registration&name=alice.xdc&years=1Returns the current USD policy price and buffered XDC estimate. It does not authorize a payment.
/api/v1/registrar/quoteReturns a short-lived signed quote bound to a payer, owner, name, policy, registrar, and nonce.
/api/pay-linksStores an already signed payment request and returns its shareable path plus a private revocation token.
/api/pay-links/cancellations/{requestId}Returns active, cancelled, or paid so an integration can update immediately after completion.
/address-bookWallet owners can save exchange, asset, network, address and memo together. Records are encrypted and require a short-lived wallet-authorized vault session.
TypeScript SDK
Use the on-chain client for resolution and owner-authorized transaction preparation, or the HTTP client for server and browser integrations. Signed quotes cover registration, renewal, discount grants, and subdomains; Pay Link helpers cover creation, status, lookup, and revocation.
Version 0.2 is available only from this repository for review and integration testing. Do not use npm install @xdcid/sdk yet: the package has not been published to npm.
import { createXdcidClient } from "@xdcid/sdk";
const xdcid = createXdcidClient();
const result = await xdcid.resolveName("alice.xdc");Integration recipes
These flows keep signing in the user's wallet and use XDCID's API only where current policy, authorization, or durable Pay Link state is required.
Web2 or backend
Use the typed API client from Node.js, a browser, or any runtime with fetch. No wallet or API key is required for public reads.
import { createXdcidApiClient } from "@xdcid/sdk/api";
const api = createXdcidApiClient();
const result = await api.getName("alice.xdc");
const primary = await api.reverseResolve(wallet);Wallet application
Request a ten-minute quote, then let the payer approve USDC when needed and submit the prepared registrar call from their own wallet.
const quote = await api.createRegistrarQuote({
name: "alice.xdc", product: "registration",
termYears: 1, paymentCurrency: "USDC",
payer: account, nameOwner: account
});
const plan = xdcid.prepareRegistrarPayment(quote);Organizations
Parent-name owners and approved operators can create wallet-owned subdomains using short-lived signed quotes.
const quote = await api.createSubdomainQuote({
parentName: "company.xdc", label: "alice",
action: "registration", termYears: 1,
paymentCurrency: "XDC", payer: account,
subdomainOwner: account
});Payments
Store an already signed request, render its short path or QR code, and poll its request ID until the link becomes paid or cancelled.
const link = await api.createPayLink({ request, signature });
const status = await api.getPayLinkStatus(requestId);
// Keep link.revocationToken private.Success format
Every application JSON response identifies the API version. Clients should ignore response fields they do not recognize.
{
"version": "v1",
"data": {
"name": "alice.xdc",
"available": false,
"resolvedAddress": "0x..."
}
}Error format
Invalid input returns HTTP 400, rate limits may return 429, and temporary XDC RPC failures return 503.
{
"version": "v1",
"error": {
"code": "INVALID_NAME",
"message": "Invalid XDCID name"
}
}XDC AI Gateway
The XDCID service is available through XDC AI for 0.001 USDC per call. Agents should use the service URL published by XDC AI; protected upstream credentials remain server-side and are never required by callers.
Resolve an XDCID name to its owner, payment address, and expiry.
Find the verified primary XDCID name for an XDC address.
Check whether a name is available and retrieve its registration price.
Read the public profile records attached to an XDCID name.
List every active XDCID name owned by an address, including its verified primary ID.
New optional fields may be added within v1. Removing fields, renaming fields, changing their types, or changing documented behavior requires a new API version.
View the complete schemas and status codes →