Stack API

1sat-stack

Composable BSV indexing server consolidating overlay engine, TXO indexer, BSV21 tokens, ORDFS, and BAP identity into a single API.

Production API base: https://api.1sat.app/1sat

Source: https://github.com/b-open-io/1sat-stack

Core API Endpoints

All endpoints are prefixed with /1sat on the hosted instance.

Transaction Outputs (TXOs)

GET  /txo/{outpoint}              Get a specific output (e.g., txid.0)
GET  /txo/tx/{txid}               All outputs for a transaction
GET  /txo/search                  Search outputs by key(s) via query params
POST /txo/outpoints               Bulk fetch multiple outpoints
POST /txo/spends                  Check spend status of outpoints
GET  /txo/{outpoint}/spend        Get spending txid for an output

Owner (Address) Queries

GET  /owner/{owner}/txos          Stream unspent outputs via SSE (see pattern below)
GET  /owner/{owner}/balance       Satoshi balance for an owner
GET  /owner/sync                  Multi-owner sync via SSE (query: ?owner=addr1&owner=addr2)

/owner/{owner}/txos is an SSE endpoint — it streams sync progress, then individual TXO events, then a done event. Use EventSource or read the stream manually (see pattern below).

Use owner endpoints as the primary way to fetch UTXOs before building transactions.

BEEF Transactions

GET  /beef/{txid}                 Full BEEF (tx + merkle proof)
GET  /beef/{txid}/tx              Raw transaction bytes only
GET  /beef/{txid}/proof           Merkle proof bytes only

Broadcasting (Arcade wrap)

Arcade-shaped routes under /1sat/arcade. Legacy POST /tx and GET /tx/{txid} remain. SSE and batch /txs are not wrapped.

POST /arcade/tx                   Broadcast single tx/BEEF (wait for status)
POST /arcade/txs                  Batch of concatenated raw txs (octet-stream)
GET  /arcade/tx/{txid}            Broadcast status
GET  /arcade/policy               Mining policy (fee + size limits)

BSV21 Fungible Tokens

GET  /bsv21/{tokenId}                                        Token details
POST /bsv21/{tokenId}/outputs                                Validate outpoints in token topic (body: string[])
GET  /bsv21/{tokenId}/outputs/{outpoint}                     Validate single outpoint in token topic
GET  /bsv21/{tokenId}/{lockType}/{address}/balance           Token balance for address
GET  /bsv21/{tokenId}/{lockType}/{address}/unspent           Unspent token UTXOs
GET  /bsv21/{tokenId}/{lockType}/{address}/history           Token history for address
POST /bsv21/lookup                                           Bulk lookup tokens by ID array (body: string[], max 100)
GET  /bsv21/{tokenId}/blk/{height}                           Block data for token at height
GET  /bsv21/{tokenId}/tx/{txid}                              Transaction details for token (inputs + outputs)
POST /bsv21/{tokenId}/{lockType}/balance                     Multi-address balance (body: string[], max 100)
POST /bsv21/{tokenId}/{lockType}/history                     Multi-address history (body: string[], max 100)
POST /bsv21/{tokenId}/{lockType}/unspent                     Multi-address unspent (body: string[], max 100)

lockType is typically p2pkh.

Collections (optional module)

The collection overlay is a separate, disabled-by-default module. A self-hosted deployment can mount its routes at /collection, but this does not establish that the hosted API enables them. Load ../collections/SKILL.md for admission, topics, routes, and the SDK compatibility warning.

ORDFS (On-chain Content)

Content endpoint is at /content/ — NOT under the /1sat/ prefix.

GET  /content/{outpoint}[:{seq}][/filename]   Serve inscription content
GET  /ordfs/metadata/{outpoint}[:{seq}]       Content metadata (JSON)
POST /ordfs/metadata                          Bulk metadata (body: {"outpoints": [...]}, max 100)
GET  /ordfs/stream/{outpoint}                 Stream chunked ORDFS content (supports Range headers)

Sequence parameter (:seq) — appended to outpoint with a colon, controls transfer chain resolution:

Query params:

• ?map=true — include merged MAP metadata in X-Map response header
• ?parent=true — include parent outpoint in X-Parent response header
• ?out=true — include resolved outpoint details
• ?raw — for directory inscriptions (ord-fs/json), return raw JSON instead of redirecting

Response headers (present when seq is used):

• X-Outpoint — resolved outpoint
• X-Origin — origin outpoint
• X-Ord-Seq — resolved sequence number
• X-Map — merged MAP JSON (when ?map=true)
• X-Parent — parent outpoint (when ?parent=true)

Directory traversal: Inscriptions with content type ord-fs/json are directories. Append /filename to the path to resolve files within the directory. Requesting a directory root redirects to index.html. If the file isn't found, index.html is served (SPA fallback).

Caching: Specific sequences (seq >= 0, seq == -2) are immutable-cached. Latest (seq == -1) uses no-cache.

For full details on the sequence model, content resolution, streaming, and DNS routing, see pkg/ordfs/README.md in the 1sat-stack repo.

BAP Identity

GET  /bap/profile/{bapId}         Profile for a BAP identity
POST /bap/identity/get            Resolve identity from address or idKey
GET  /bap/identity/search         Search identities by query

Identity + Subscription Integration: These endpoints feed into Sigma Identity's NFT subscription system. When a user connects a wallet to Sigma, it queries 1sat-stack for NFTs owned by that wallet, checks NFT origins against subscription tier config (Free/Plus/Pro), and grants access. The /owner/{address}/txos endpoint returns ordinals with their origin txids — the origin determines the subscription tier.

BAP ID Resolution: The /bap/identity/get endpoint resolves a pubkey or address to a BAP identity key. Sigma uses this for identity verification during OAuth flows and for ClawNet trust scoring.

Real-time Streaming

GET  /sse/{topics}                SSE stream for comma-separated topic events
GET  /chaintracks/tip/stream      SSE stream of new block tips

Chain Info

GET  /chaintracks/height          Current chain height
GET  /chaintracks/tip             Latest block header
GET  /health                      Server health check

OpNS (On-chain Naming)

GET  /opns/mine/{name}            Get mining status for a domain name

BSocial (Social Posts)

GET  /bsocial/post/search         Full-text search posts (?q=query&limit=20&offset=0)

Paymail (BSV Alias Protocol)

GET  /.well-known/bsvalias                          Capability discovery document
GET  /v1/bsvalias/id/{paymail}                      PKI — get public key for paymail address
POST /v1/bsvalias/p2p-payment-destination/{paymail} Get P2P payment destination (BRC-29)
POST /v1/bsvalias/receive-beef/{paymail}             Receive BEEF payment
POST /v1/bsvalias/receive-transaction/{paymail}      Receive raw transaction payment

Overlay Engine (Advanced)

POST /overlay/submit              Submit tagged BEEF to the overlay
POST /overlay/lookup              Query the overlay lookup services
GET  /overlay/listTopicManagers   List active topic managers
GET  /overlay/listLookupServiceProviders  List active lookup services

Common Patterns

Fetch UTXOs to Build a Transaction (SSE)

const es = new EventSource('https://api.1sat.app/1sat/owner/1A1zP1.../txos?tags=*');
const utxos: any[] = [];
es.addEventListener('txo', (e) => utxos.push(JSON.parse(e.data)));
es.addEventListener('done', () => {
  es.close();
  // utxos: array of {outpoint, satoshis, data, score, ...}
});
es.addEventListener('error', () => es.close());

Broadcast a Transaction

const res = await fetch('https://api.1sat.app/1sat/arcade/tx', {
  method: 'POST',
  headers: { 'Content-Type': 'application/octet-stream' },
  body: beefHex  // BEEF format
});
const result = await res.json();
// result.txid on success

Get BSV21 Token Balance

const tokenId = 'abc123...'; // BSV21 token ID (txid of deploy)
const address = '1A1zP1...';
const res = await fetch(
  `https://api.1sat.app/1sat/bsv21/${tokenId}/p2pkh/${address}/balance`
);
const { balance } = await res.json();

Search for Outputs by Key

// Search uses GET with query params. Keys use prefixes: "ev:" for events, "tp:" for topics.
// Without prefix, "ev:" is assumed. Use "own:" prefix for owner lookups.
const params = new URLSearchParams({
  key: 'own:1A1zP1...',
  unspent: 'true',
  tags: 'inscription',
  limit: '100'
});
const res = await fetch(`https://api.1sat.app/1sat/txo/search?${params}`);
const outputs = await res.json();

Authentication

Most endpoints are public. For higher rate limits, add an API key:

headers: { 'Authorization': 'Bearer YOUR_API_KEY' }

Rate limits:

• Public: 100 req/min
• Authenticated: 1000 req/min

Self-Hosting

1sat-stack is open source and deployable on Railway. Each service module is configured via config.yaml with mode: embedded | remote | disabled. See config.example.yaml in the repo for full options.

Reference Files

For detailed endpoint parameters and response schemas, see:

• references/api-reference.md — Full endpoint reference with request/response details
• examples/migration-guide.md — Before/after patterns migrating from WOC + GorillaPool + others
• scripts/query-unified.ts — Working TypeScript examples for all major operations