ordfs

This skill should be used when the user asks "what is ORDFS", "how to use ordfs.network", "ordfs API", "access on-chain content", "inscription gateway", "ordfs query parameters", "ordfs sequence", "ordfs directory", "ordfs preview", "recursive inscriptions", "ord-fs/json", or needs to reference, access, or serve on-chain content through ORDFS.

b-open-io 7 Updated 7mo ago

Resources

GitHub

Install

npx skillscat add b-open-io/bsv-skills/ordfs

Install via the SkillsCat registry.

About this skill

This skill provides an HTTP gateway for accessing on-chain inscriptions from the BSV blockchain through the ORDFS network. It enables retrieval of content, metadata, directory listings, and specific versions using various endpoint patterns and query parameters. Agents should use this skill when users need to reference, access, or serve on-chain content via the ordfs.network gateway or its API endpoints.

SKILL.md

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/go-ordfs-server

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.

Special "-1" (Latest)

/content/{pointer}         # Same as :-1, gets latest version
/content/{pointer}:-1      # Explicit latest

Behavior: Short TTL caching (60s), returns most recent version.

Specific Sequence

/content/{pointer}:0       # Original inscription
/content/{pointer}:5       # 5th update

Behavior: Long TTL caching (30 days), immutable content.

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

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

User visits yourdomain.com/path/to/file
ORDFS resolves DNS TXT record
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
js-1sat-ord - Create inscriptions
@bopen-io/templates - Inscription templates

ordfs

Resources

Install

ORDFS - Ordinals File System

Quick Reference

Content Access Patterns

Basic Content URL

Outpoint Formats

Content Endpoint with Options

Sequence Versioning

Special "-1" (Latest)

Specific Sequence

Response Headers

Directories (ord-fs/json)

Directory Format

Accessing Directory Files

SPA Routing

Raw Directory JSON

Preview Endpoint

Base64 HTML Preview

POST Preview

Recursive Inscriptions

Pattern

Base Path Handling

API Endpoints

V1 Endpoints

V2 Endpoints

DNS-Based Access

DNS TXT Record

How It Works

Common Usage Patterns

Image Display

Fetch Content

Check Latest Version

Caching Behavior

Additional Resources

Reference Files

Examples

Related Packages

Categories

Install

Recommended Skills