#601

Global Rank · of 601 Skills

ordfs AI Agent Skill

View Source: b-open-io/bsv-skills

Medium

Installation

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

19

Installs

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

Installs

Installs 19
Global Rank #601 of 601

Security Audit

ath Safe
socket Safe
Alerts: 0 Score: 90
snyk Medium
EU EU-Hosted Inference API

Power your AI Agents with the best open-source models.

Drop-in OpenAI-compatible API. No data leaves Europe.

Explore Inference API

GLM

GLM 5

$1.00 / $3.20

per M tokens

Kimi

Kimi K2.5

$0.60 / $2.80

per M tokens

MiniMax

MiniMax M2.5

$0.30 / $1.20

per M tokens

Qwen

Qwen3.5 122B

$0.40 / $3.00

per M tokens

How to use this skill

1

Install ordfs by running npx skills add b-open-io/bsv-skills --skill ordfs in your project directory. Run the install command above in your project directory. The skill file will be downloaded from GitHub and placed in your project.

2

No configuration needed. Your AI agent (Claude Code, Cursor, Windsurf, etc.) automatically detects installed skills and uses them as context when generating code.

3

The skill enhances your agent's understanding of ordfs, helping it follow established patterns, avoid common mistakes, and produce production-ready output.

What you get

Skills are plain-text instruction files — not executable code. They encode expert knowledge about frameworks, languages, or tools that your AI agent reads to improve its output. This means zero runtime overhead, no dependency conflicts, and full transparency: you can read and review every instruction before installing.

Compatibility

This skill works with any AI coding agent that supports the skills.sh format, including Claude Code (Anthropic), Cursor, Windsurf, Cline, Aider, and other tools that read project-level context files. Skills are framework-agnostic at the transport level — the content inside determines which language or framework it applies to.

Data sourced from the skills.sh registry and GitHub. Install counts and security audits are updated regularly.

EU Made in Europe

Chat with 100+ AI Models in one App.

Use Claude, ChatGPT, Gemini alongside with EU-Hosted Models like Deepseek, GLM-5, Kimi K2.5 and many more.

Start for free View pricing

Get the App:

Download on the App Store Get it on Google Play
Customer Support