TypeScript client

The client is generated from the OpenAPI documents and lives in packages/client. It is regenerated by npm run generate, and CI fails if the committed output differs.

What the client will never do

It does not sign, broadcast, request key material, or embed a credential. Those belong in a wallet and in your own server, not in a generated read client.

Install and configure

The base URL is required. There is no default, because a default would be a production host baked into a package.

TypeScript

import { AtomicalsClient } from '@bitcoin-universe/atomicals-client'

const client = new AtomicalsClient({
  baseUrl: process.env.ATOMICALS_API_URL!,
  // Optional. Only for surfaces that require it. Never ship this in a browser.
  bearerToken: process.env.ATOMICALS_API_TOKEN,
})

const asset = await client.getAsset({
  atomicalId: '4d0b1f1c9c53a5b1e0b1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5061i0',
})

console.log(asset.data.atomicalId, asset.generationId, asset.requestId)

JavaScript

import { AtomicalsClient } from '@bitcoin-universe/atomicals-client'

const client = new AtomicalsClient({ baseUrl: process.env.ATOMICALS_API_URL })

const ready = await client.getReady()
if (!ready.data.ready) {
  console.error('not ready:', ready.data.reason)
  process.exit(1)
}

Typed errors

Failures throw a typed error carrying the status, the machine readable code, and the request identifier. Branch on the code, never on the message.

import { AtomicalsClient, AtomicalsApiError } from '@bitcoin-universe/atomicals-client'

try {
  await client.getNft({ atomicalId })
} catch (error) {
  if (error instanceof AtomicalsApiError) {
    if (error.code === 'NFT_NOT_FOUND') {
      // Not in the active generation. Check readiness before concluding it is gone.
    }
    console.error(error.status, error.code, error.requestId)
  }
  throw error
}

Pagination

The helper restarts the listing when the generation changes, rather than continuing with a cursor that is no longer valid.

for await (const page of client.paginate.listNfts({ limit: 100 })) {
  for (const asset of page.items) {
    // page.generationId is stable across this loop.
  }
}

Freshness

Every response exposes the generation identifier, the indexed height, and the request identifier alongside the parsed body. Store them with anything you cache.

const page = await client.listRealms({ limit: 50 })
console.log(page.generationId, page.indexedHeight, page.requestId)

What is included

Included	Not included
Public read operations for both indexes	Anything that signs or broadcasts
Marketplace read operations and contract types	Marketplace mutation request signing
Typed errors and pagination helpers	Credential storage or management
Freshness metadata on every response	A default base URL

Marketplace mutations require an HMAC over exact body bytes and an owner session. Those belong in your server, where the secret lives. The client exposes the types so you can build the request, and deliberately does not sign it for you.

Source

OpenAPI and downloads and migration.