This skill should be used when working with the 1sat-stack unified BSV indexing API — whenever an agent needs to fetch UTXOs, look up inscriptions or ordinals, get BSV21 token balances, access ORDFS on-chain content, broadcast transactions, look up BAP identities, or stream real-time BSV events. Use this when replacing WhatsOnChain, GorillaPool ordinals API, or other separate BSV indexers. Also use when the user asks about 'api.1sat.app', 'unified BSV indexer', 'BSV21 token lookup', 'ORDFS content', 'overlay engine', or 'broadcasting BEEF transactions'.
From 1satnpx claudepluginhub b-open-io/claude-plugins --plugin 1satThis skill uses the workspace's default tool permissions.
examples/migration-guide.mdreferences/api-reference.mdscripts/query-unified.tsDesigns and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Enables AI agents to execute x402 payments with per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents pay for APIs, services, or other agents.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
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
All endpoints are prefixed with /1sat on the hosted instance.
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
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.
GET /beef/{txid} Full BEEF (tx + merkle proof)
GET /beef/{txid}/tx Raw transaction bytes only
GET /beef/{txid}/proof Merkle proof bytes only
POST /arcade/tx Broadcast single BEEF transaction
POST /arcade/txs Broadcast multiple BEEF transactions
GET /arcade/tx/{txid} Check broadcast status
GET /arcade/policy Fee rates and transaction limits
GET /arcade/events/{token} SSE stream of broadcast status updates
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.
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:
| seq | Behavior |
|---|---|
| omitted | Raw content from exact outpoint. No origin resolution, no crawl. |
-2 | Origin only. Backward crawl to find origin, return its content. |
0 | Content at requested outpoint + origin metadata in headers. |
-1 | Latest. Forward crawl to tip of transfer chain. |
N | Content at specific absolute sequence number. |
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 redirectingResponse headers (present when seq is used):
X-Outpoint — resolved outpointX-Origin — origin outpointX-Ord-Seq — resolved sequence numberX-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.
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.
GET /sse/{topics} SSE stream for comma-separated topic events
GET /chaintracks/tip/stream SSE stream of new block tips
GET /chaintracks/height Current chain height
GET /chaintracks/tip Latest block header
GET /health Server health check
GET /opns/mine/{name} Get mining status for a domain name
GET /bsocial/post/search Full-text search posts (?q=query&limit=20&offset=0)
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
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
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());
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
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 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();
Most endpoints are public. For higher rate limits, add an API key:
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
Rate limits:
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.
For detailed endpoint parameters and response schemas, see:
references/api-reference.md — Full endpoint reference with request/response detailsexamples/migration-guide.md — Before/after patterns migrating from WOC + GorillaPool + othersscripts/query-unified.ts — Working TypeScript examples for all major operations