b-open-io/ordfs

ORDFS - Ordinals File System

HTTP gateway for accessing on-chain content (inscriptions) from BSV blockchain.

Live Gateway: https://ordfs.network Repository: https://github.com/b-open-io/1sat-stack

Quick Reference

| Endpoint | Purpose | |----------|---------| | /{txid}_{vout} | Direct content access | | /content/{pointer} | Content with options | | /content/{pointer}:{seq} | Specific version | | /content/{pointer}/{file} | File from directory | | /preview/{b64Html} | Preview HTML code | | /v2/metadata/{outpoint} | Metadata only |

Content Access Patterns

Basic Content URL

https://ordfs.network/{txid}_{vout}

Example:

https://ordfs.network/abc123...def_0

Outpoint Formats

All formats resolve to the same content:

| Format | Example | |--------|---------| | Underscore | abc123..._0 | | Period | abc123....0 | | Txid only | abc123... (defaults to vout 0) |

Content Endpoint with Options

/content/{pointer}[:{sequence}][/{filepath}]

Query Parameters:

| Param | Default | Description | |-------|---------|-------------| | content | true | Include content data | | map | false | Include MAP metadata | | out | false | Include raw output (base64) | | parent | false | Include parent reference | | raw | - | Return directory JSON instead of index.html |

Examples:

/content/abc123..._0?map=true          # With MAP metadata
/content/abc123..._0?content=false     # Metadata only
/content/abc123..._0?raw               # Directory listing

Sequence Versioning

Track inscription updates using sequence numbers.

No Sequence (Raw Content)

/content/{pointer}         # Raw content from the outpoint, no origin resolution

Behavior: Returns content directly from the specified outpoint. No crawl is performed.

Sequence Values

| Seq | Behavior | |-----|----------| | (none) | Raw content from the outpoint, no origin resolution, no crawl | | -2 | Origin only — backward crawl to find origin, returns origin data, no forward crawl | | 0 | Resolve at the requested outpoint, also resolves origin to return in metadata | | -1 | Latest state — full forward crawl to current tip | | N (positive) | Specific sequence in the ordinal's transfer chain |

/content/{pointer}:-2      # Origin only
/content/{pointer}:0       # Resolve at outpoint, with origin metadata
/content/{pointer}:-1      # Latest state (full forward crawl)
/content/{pointer}:5       # 5th transfer in chain

Caching

• Specific sequence (:N where N >= 0): Long TTL (30 days), immutable content
• Latest (:-1): Short TTL (60s)

Response Headers

| Header | Description | |--------|-------------| | X-Outpoint | Current outpoint | | X-Origin | Original inscription outpoint | | X-Ord-Seq | Sequence number | | X-Map | JSON MAP metadata | | X-Parent | Parent inscription outpoint |

Directories (ord-fs/json)

Inscriptions with content type ord-fs/json represent directories.

Directory Format

{
  "index.html": "ord://abc123..._0",
  "style.css": "abc123..._1",
  "app.js": "def456..._0"
}

Values can be:

• ord://txid_vout - Full ordinal reference
• txid_vout or txid - Direct reference
• _N - Relative vout reference (resolved to {manifest_txid}_N)

Relative Vout Resolution (_N)

ORDFS natively resolves _N patterns in directory manifests. When an ord-fs/json entry has a value like _1, ORDFS resolves it to {manifest_txid}_1 — the sibling output in the same transaction.

{
  "SKILL.md": "_1",
  "README.md": "_2",
  "lib/utils.ts": "_3"
}

Clients do NOT need to parse the manifest and construct outpoint URLs. Instead, request files by path:

/content/{manifest_outpoint}/SKILL.md      → resolves _1 → {txid}_1
/content/{manifest_outpoint}/lib/utils.ts  → resolves _3 → {txid}_3

Recursive Directory Traversal

ORDFS supports nested directories. If a directory entry points to another ord-fs/json inscription, ORDFS recurses into it automatically:

{
  "SKILL.md": "_1",
  "references": "_2"
}

Where _2 is itself an ord-fs/json manifest:

{
  "api-docs.md": "_1",
  "examples.md": "_2"
}

Accessing /content/{root_manifest}/references/api-docs.md traverses both levels.

Accessing Directory Files

/content/{directory_pointer}/index.html
/content/{directory_pointer}/style.css
/content/{directory_pointer}/app.js

SPA Routing

For SPAs, unknown paths fall back to index.html:

/content/{pointer}/unknown/path  → Returns index.html

Raw Directory JSON

Add ?raw to get the directory listing instead of index.html:

/content/{pointer}?raw

Preview Endpoint

Test HTML inscriptions before broadcasting.

Base64 HTML Preview

/preview/{base64EncodedHtml}

Example:

const html = "<html><body>Hello!</body></html>";
const b64 = btoa(html);
const previewUrl = `https://ordfs.network/preview/${b64}`;

POST Preview

curl -X POST https://ordfs.network/preview \
  -H "Content-Type: text/html" \
  -d "<html><body>Hello!</body></html>"

Recursive Inscriptions

Reference other inscriptions from HTML/JS content.

Pattern

<script src="/content/abc123..._0"></script>
<img src="/def456..._0" />
<link href="/content/style123..._0/main.css" rel="stylesheet">

Base Path Handling

ORDFS sets up base paths for recursive content to resolve correctly.

API Endpoints

V1 Endpoints

| Endpoint | Purpose | |----------|---------| | /v1/bsv/block/latest | Latest block info | | /v1/bsv/block/height/{h} | Block by height | | /v1/bsv/block/hash/{hash} | Block by hash | | /v1/bsv/tx/{txid} | Raw transaction |

V2 Endpoints

| Endpoint | Purpose | |----------|---------| | /v2/tx/{txid} | Raw transaction | | /v2/tx/{txid}/proof | Merkle proof | | /v2/tx/{txid}/beef | BEEF format proof | | /v2/tx/{txid}/{vout} | Specific output | | /v2/block/tip | Latest block header | | /v2/chain/height | Current height | | /v2/metadata/{outpoint} | Inscription metadata | | /v2/stream/{outpoint} | Streaming content |

DNS-Based Access

Map custom domains to inscriptions.

DNS TXT Record

Create _ordfs.yourdomain.com:

_ordfs.yourdomain.com IN TXT "ordfs=abc123..._0:5"

Format: ordfs={pointer}[:{sequence}]

How It Works

1. User visits yourdomain.com/path/to/file
2. ORDFS resolves DNS TXT record
3. Returns content from inscription directory

Common Usage Patterns

Image Display

// Using bitcoin-image for normalization
import { getDisplayUrl } from "bitcoin-image";

const imageUrl = await getDisplayUrl("ord://abc123..._0");
// Returns: https://ordfs.network/abc123..._0

// Direct construction
const url = `https://ordfs.network/${txid}_${vout}`;

Fetch Content

// Get inscription content
const response = await fetch(`https://ordfs.network/${origin}`);
const content = await response.text();

// Get with metadata
const metaResponse = await fetch(
  `https://ordfs.network/content/${origin}?map=true`
);
const mapData = metaResponse.headers.get("X-Map");

Check Latest Version

// Get latest sequence
const response = await fetch(`https://ordfs.network/content/${origin}`);
const sequence = response.headers.get("X-Ord-Seq");
const currentOutpoint = response.headers.get("X-Outpoint");

Caching Behavior

| Request Type | Cache TTL | |--------------|-----------| | Specific sequence (:N) | 30 days | | Latest sequence (default) | 60 seconds | | Block headers (depth 100+) | 30 days | | Block headers (depth 4-99) | 1 hour | | Block tip | No cache |

Additional Resources

Reference Files

• references/api-reference.md - Complete API documentation
• references/advanced-features.md - DNS, streaming, directories

Examples

• examples/fetch-content.ts - Content fetching patterns
• examples/recursive-inscription.html - Recursive inscription example

Related Packages

• bitcoin-image - URL normalization for ordfs.network
• @1sat/actions - Create inscriptions
• @1sat/templates - Inscription templates