Resolve API & SDK

Look up who owns a handle. Resolution is read-only and public — no wallet, no signature, and no API key. The REST base URL is https://api.x1id.io; there is no /v1 prefix. The REST endpoint returns the handle’s owner; for per-chain addresses (X1 / SOL / ETH / BTC), records, and on-chain writes, use the @x1id/resolve SDK below.

Handles, not domains. X1ID handles (@jack) and X1NS domains (jack.x1) are complementary — this API resolves handles. See how they fit together.

The @handle registry is deployed on X1 testnet today. Resolutions reflect testnet state until the mainnet cutover, which is a separate, deliberate step — see Trust & transparency.

Resolve a handle

GET /resolve/{name}

Look up the owner of a handle.

string

required

The handle to resolve, with or without the leading @. Case-insensitive — x1 and @X1 resolve the same record. Given as a path segment: /resolve/x1.

Response

Returns the resolution object for the handle. It reports the current owner and whether the handle is tokenized — it does not carry an addresses map or an expiry (names are permanent, so there is nothing to expire). An unregistered handle returns 404 { "error": "handle not registered" }.

curl https://api.x1id.io/resolve/x1

{
  "input": "x1",
  "name": "x1",
  "namespace": "handle",
  "owner": "H8FsKYhMyCN9brknY7tL4JXRbKZEjVh7XgrVmWcX1HiA",
  "tokenized": false,
  "verification": "owner"
}

string

The raw value you passed.

string

The normalized handle (no @).

string

Always handle for this endpoint.

string

The wallet that owns the handle. For a tokenized handle this is informational — authority follows the NFT holder.

boolean

Whether the handle has been turned into an NFT.

string

owner when the owner controls the registry account.

Ownership you can audit. Every handle is a record on the X1 registry program (8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P), so a resolution can be verified independently on-chain. See Trust & transparency.

Reverse lookup

GET /reverse/{address}

Go the other way — an address back to its @handle. Only the address the owner has explicitly marked as their primary reverse-resolves, which is what prevents impersonation. An address with no primary returns 404 { "error": "no primary set" }.

string

required

A base58 wallet address to reverse-resolve to its primary handle.

curl https://api.x1id.io/reverse/H8FsKYhMyCN9brknY7tL4JXRbKZEjVh7XgrVmWcX1HiA

{
  "error": "no primary set",
  "input": "H8FsKYhMyCN9brknY7tL4JXRbKZEjVh7XgrVmWcX1HiA"
}

When the address has a primary handle, the response carries that handle instead. A primary is only returned when it is still trustworthy — the pointer and the handle it names both exist, the pointer was set after the handle’s current registration, and the address still holds authority over the name.

Health

GET /health

A liveness check for the service.

curl https://api.x1id.io/health

{ "ok": true }

SDK: multi-chain, records, and writes

The REST endpoint answers “who owns this handle.” For per-chain addresses, records, and on-chain writes, use the @x1id/resolve SDK (0.3.0). It reads chain state directly over RPC — it never depends on this API’s uptime — and its writes are unsigned instruction builders you sign and relay yourself; the SDK never holds keys. The @handle registry is on X1 testnet today (https://rpc.testnet.x1.xyz).

npm install @x1id/resolve@0.3.0

Address derivation runs in a small Rust→WASM module, so createResolver needs the WASM bytes. The package ships them at @x1id/resolve/wasm/x1_resolve_wasm.wasm — load them once and reuse the resolver. Full loading recipes (Node and browser) are in the SDK README.

Read: resolve across chains

resolve(input, { chain }) returns a Resolved object. X1/SOL come from the handle’s authority; ETH/BTC from its on-chain records. A handle with no record for the requested chain is explicit (no-record-for-chain), never a wrong address on the wrong chain.

import { createResolver, WasmResolver } from '@x1id/resolve';

const wasm = await WasmResolver.fromBytes(/* module bytes */);
const x1id = createResolver({ rpcUrl: 'https://rpc.testnet.x1.xyz', wasm });

const r = await x1id.resolve('@x1', { chain: 'SOL' });
// {
//   input: '@x1', name: 'x1', namespace: 'handle',
//   address: 'H8FsKYhMyCN9brknY7tL4JXRbKZEjVh7XgrVmWcX1HiA',
//   chain: 'SOL', verification: 'verified'
// }

// A handle with no record for the requested chain is explicit, never a
// wrong address: resolve('@x1', { chain: 'ETH' }) throws
// ResolveError { code: 'no-record-for-chain' }.

Show the namespace before you send. @jack and jack.x1 can resolve to different owners, so every result carries its namespace. Render it — @jack or jack.x1 — in the recipient field before a transfer is committed. @jack.x1 (both shapes at once) throws ResolveError { code: 'ambiguous' } rather than guessing.

Read: reverse and records

const name = await x1id.reverse(address);
// 'nike'  → the address's primary @handle (canonical, no '@')
// null    → no primary set

const recs = await x1id.records('@x1');
// HandleRecord[]: { account, handle, coinType, chain, value, address,
//                   verified, updatedAt, stale }   ([] when none are set)

Records are judged against a universal staleness rule: a record whose updatedAt predates the handle’s current registration was left behind by a previous owner of the same name, so it is flagged stale and its stored verified is forced to false. Use the exported liveRecords(recs) to keep only the ones that belong to the current owner.

Write: sign and relay yourself

Registration and set_primary run from app.x1id.io today. The SDK ships builders for the rest of the registry — each returns an unsigned { programId, keys, data } you assemble, sign, and send:

import { buildCreateSubnameIx } from '@x1id/resolve';

const ix = buildCreateSubnameIx({
  programId,          // 8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P
  payer,              // signer — funds the subname account's rent
  owner,              // signer — the parent handle's current authority
  parent,             // the parent ["handle", name] PDA
  subname,            // the ["subname", parent, label] PDA
  label: 'team',      // issues team.you
});
// add ix to a transaction, sign with payer + owner, send.

Also shipped, same build → sign → relay shape:

Capability	Builders
Gift a handle (prepaid voucher)	`buildCreateVoucherIx` (+ `HandleType`), `buildClaimVoucherIx`, `buildRefundVoucherIx`
Integrator rev-share	`buildAddIntegratorIx`, `buildSetIntegratorRateIx`, `buildRemoveIntegratorIx`
Name lock / timelocked unlock	`buildLockHandleIx`, `buildInitiateUnlockIx`, `buildCompleteUnlockIx`, `buildCancelUnlockIx`
Record-write delegation	`buildSetRecordDelegateIx`, `buildRevokeRecordDelegateIx`
Typed text records (website / avatar / socials)	`buildCreateTextRecordIx`, `buildUpdateTextRecordIx`, `buildCloseTextRecordIx`
Domain / social attestations	`buildCreateAttestationIx`, `buildCloseAttestationIx`

Which RPC? Point the resolver at the chain that holds the names you want. @handle resolution is on X1 testnet today; on an RPC where the registry is not deployed a handle is an honest not-found, never a fabricated address. The full builder list, PDA seeds, and error codes are in the SDK README.

Welcome

Using X1ID

Developers

Good to know

Resolve API & SDK

Resolve API & SDK

Resolve a handle

Response

Reverse lookup

Health

SDK: multi-chain, records, and writes

Read: resolve across chains

Read: reverse and records

Write: sign and relay yourself

​Resolve API & SDK

​Resolve a handle

​Response

​Reverse lookup

​Health

​SDK: multi-chain, records, and writes

​Read: resolve across chains

​Read: reverse and records

​Write: sign and relay yourself

Resolve API & SDK

Resolve a handle

Response

Reverse lookup

Health

SDK: multi-chain, records, and writes

Read: resolve across chains

Read: reverse and records

Write: sign and relay yourself