Developer documentation

Build with XDCID

Resolve human-readable .xdc names, integrate production APIs and contracts, and review clearly labelled preview tooling.

NetworkXDC mainnet
Chain ID50

Private destination vault

Encrypted exchange destinations

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.

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.

What encryption means

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.

How access is scoped

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

A signature unlocks the vault

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.

  • Short-lived challenge: the signing request expires after five minutes and can be used only once.
  • Thirty-minute session: successful verification creates a secure, HTTP-only vault session bound to the wallet and current client context.
  • Wallet changes: switching accounts, disconnecting, expiring the session, or selecting Lock now requires verification again.

Deposit safety

Network and memo warnings

Match the exchange exactly

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.

Saved routes update together

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.

Memo or tag payments are blocked

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.

Reconfirm changed details

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

Supported payment routes

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.

NetworkNative assetChain IDDirect payments
EthereumETH1USDC and the network's native asset
XDC NetworkXDC50USDC and the network's native asset
PolygonPOL137USDC and the network's native asset
BaseETH8453USDC and the network's native asset
Arbitrum OneETH42161USDC and the network's native asset

Same-network direct

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.

Cross-network USDC

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.

Not supported

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 endpoints

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.

GET/api/v1/names/{name}?years=1

Name lookup

Returns the canonical name, owner, resolved address, availability, registration price, expiry, and profile records.

GET/api/v1/reverse/{address}

Reverse lookup

Returns the verified primary XDCID name for a wallet address, or null when no current record exists.

GET/api/v1/addresses/{address}/names

Owned names

Returns the verified primary ID and every active XDCID name currently owned by a wallet.

GET/api/v1/pricing/quote?product=registration&name=alice.xdc&years=1

Informational pricing

Returns the current USD policy price and buffered XDC estimate. It does not authorize a payment.

POST/api/v1/registrar/quote

Registration or renewal quote

Returns a short-lived signed quote bound to a payer, owner, name, policy, registrar, and nonce.

POST/api/pay-links

Create a short Pay Link

Stores an already signed payment request and returns its shareable path plus a private revocation token.

GET/api/pay-links/cancellations/{requestId}

Monitor a Pay Link

Returns active, cancelled, or paid so an integration can update immediately after completion.

PRIVATE/address-book

Encrypted Exchange Address Book

Wallet owners can save exchange, asset, network, address and memo together. Records are encrypted and require a short-lived wallet-authorized vault session.

TypeScript SDK

One SDK for Web3 and Web2

Developer preview · Not on npm

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

Build by task

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

Resolve names over HTTPS

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

Register with a signed quote

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

Create organization subdomains

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

Share and monitor Pay Links

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

Versioned responses

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

Consistent failures

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

Paid agent capabilities

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

Resolve an XDCID name to its owner, payment address, and expiry.

Reverse

Find the verified primary XDCID name for an XDC address.

Availability

Check whether a name is available and retrieve its registration price.

Profile

Read the public profile records attached to an XDCID name.

Owned names

List every active XDCID name owned by an address, including its verified primary ID.

Compatibility policy

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 →