documentation

.bags registry

This is an off-chain registry with on-chain payment. Ownership records live in the registry database. Solana is used for one thing: collecting and verifying a flat 0.1 SOL payment before a domain is recorded.

Quickstart

curl https://your-domain.com/api/resolve/alice.bags

async function resolveDomain(domain) {
  const res = await fetch(`/api/resolve/${domain}`);
  if (res.status === 404) return null;
  const { target } = await res.json();
  return target;
}

Endpoints

GET /api/resolve/{domain}

Returns owner, target, records and registeredAt. alice and alice.bags are equivalent.

GET /api/check?name={name}

Always 200. Read available. Includes priceSol, priceLamports and treasury.

GET /api/domains

Paginated registry. Query limit, offset, q.

GET /api/wallet/{address}

Reverse lookup by owner wallet.

POST /api/register/reserve

Hold a name for ten minutes. Body: { name, wallet }.

POST /api/register/confirm

Verify the on-chain payment. Body: { reservationId, signature }.

GET /api/auth/nonce?wallet=

Single-use nonce for signed writes.

PATCH /api/domains/{name}

Update target and records. Signed.

POST /api/domains/{name}/transfer

Transfer ownership. Resets target to the new owner.

POST /api/domains/{name}/list

List or unlist. Signed. 2.5% fee on sale.

GET /api/listings

Active marketplace listings.

GET /api/offers

Open, accepted and historical bids.

POST /api/offers

Place a bid. Signed. Nothing leaves the wallet until accept + pay.

POST /api/sales/confirm

Settle a listing buy or accepted offer after the payment lands.

Name rules

ASCII first: non-ASCII is rejected before lowercasing.
a-z, 0-9 and hyphens only. 3 to 63 characters.
No leading, trailing, or consecutive hyphens.
Reserved: admin, www, api, support, help, mail, root, system, official, bags.

Payment checks

Confirmation reads the transaction at confirmed commitment. It checks that meta.err is null, the treasury (and seller, for sales) balance delta meets the required lamports, the memo matches the reservation or sale reference, and the fee payer is the expected wallet. The amount is never read from a transfer instruction.