Access media inscribed in BSV transactions. There is no dedicated extraction action exported by the SDK. Content is reached one of three ways, in order of how much machinery each needs:
| Layer | What | Best for |
|---|---|---|
| SDK service | ctx.services.ordfs.getMetadata() / getContent() (the OrdfsClient) |
In-process access from @1sat/client / @1sat/actions code |
| ORDFS HTTP gateway | Plain fetch against the gateway endpoints |
Browser/app embedding, streaming, no SDK dependency |
| txex CLI | External txex binary that writes files to disk |
Raw extraction, offline archival, batch processing |
SDK: service-level access (ctx.services.ordfs)
The SDK exposes ORDFS through the OrdfsClient at ctx.services.ordfs. There is no exported "extract" action — these are the actual methods (packages/client/src/services/OrdfsClient.ts):
// Metadata for an inscription. Pass seq -2 to resolve to the origin.
const metadata = await ctx.services.ordfs.getMetadata(outpoint, -2)
metadata.contentType // e.g. 'image/png'
metadata.origin // origin outpoint
metadata.map // MAP fields, if present
// Raw content bytes + parsed response headers.
const { data, headers } = await ctx.services.ordfs.getContent(origin)
// data: Uint8Array, headers.contentType: string
// Just the URL (for img/video tags) without fetching.
const url = ctx.services.ordfs.getContentUrl(outpoint)
// Batch metadata for many outpoints in one request.
const byOutpoint = await ctx.services.ordfs.bulkMetadata([op1, op2])
This is how the ordinals actions themselves resolve content type, origin, and MAP names — e.g. getMetadata(outpoint, -2) and getContent(origin) in packages/actions/src/ordinals/index.ts.
ORDFS HTTP gateway (no SDK)
For browser or non-SDK access, hit the gateway directly. OrdfsClient serves content from /content at the host root and metadata under the API prefix (/1sat/ordfs/... on api.1sat.app):
// Content by outpoint (txid_vout) — root-level, ordfs-protocol compatible
const url = 'https://api.1sat.app/content/abc123...def456_0'
// 1sat-stack content proxy
const url = 'https://api.1sat.app/1sat/content/abc123...def456_0'
// Stream content
const url = 'https://api.1sat.app/1sat/ordfs/stream/abc123...def456_0'
// Metadata only
const url = 'https://api.1sat.app/1sat/ordfs/metadata/abc123...def456_0'
// Public ordfs.network gateway
const url = 'https://ordfs.network/abc123...def456_0'
const res = await fetch(url)
const contentType = res.headers.get('content-type') // e.g. 'image/png'
const data = await res.arrayBuffer()
The gateway serves correct Content-Type headers, so URLs work directly in <img>, <video>, and <audio> tags.
txex CLI (external tool)
txex is a separate, third-party CLI (not part of this SDK) that extracts inscribed files to disk:
# Install
bun add -g txex
# Extract all media from a transaction
txex <txid>
# Extract to a specific output directory
txex <txid> -o /path/to/output
It writes images (PNG/JPG/GIF/WEBP), video (MP4/WEBM), audio (MP3/WAV/OGG), text/JSON/Markdown, and any binary data, with auto-detected extensions.
This skill ships a thin convenience wrapper that just shells out to txex (it is not part of the SDK runtime and exports no action):
bun run scripts/extract.ts <txid> [output-dir]
Common Use Cases
- View NFT images:
getContentUrl()or a gateway URL in<img src="..."> - Read content in code:
ctx.services.ordfs.getContent(origin)→Uint8Array - Inspect type/origin/MAP:
ctx.services.ordfs.getMetadata(outpoint, -2) - Archive media locally: batch extract with
txex - Content verification: check what's actually inscribed on-chain