ORDFS - Ordinals File System
HTTP gateway for accessing on-chain content (inscriptions) from BSV blockchain.
Quick Reference
| Endpoint | Purpose |
|---|
| Direct content access |
| Content with options |
| Specific version |
/content/{pointer}/{file}
| File from directory |
| Preview HTML code |
| 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 | |
| Period | |
| Txid only | (defaults to vout 0) |
Content Endpoint with Options
/content/{pointer}[:{sequence}][/{filepath}]
Query Parameters:
| Param | Default | Description |
|---|
| true | Include content data |
| false | Include MAP metadata |
| false | Include raw output (base64) |
| false | Include parent reference |
| - | 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 |
|---|
| Current outpoint |
| Original inscription outpoint |
| Sequence number |
| JSON MAP metadata |
| Parent inscription outpoint |
Directories (ord-fs/json)
Inscriptions with content type
represent directories.
Directory Format
json
{
"index.html": "ord://abc123..._0",
"style.css": "abc123..._1",
"app.js": "def456..._0"
}
Values can be:
- - Full ordinal reference
- or - 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
:
/content/{pointer}/unknown/path → Returns index.html
Raw Directory JSON
Add
to get the directory listing instead of index.html:
Preview Endpoint
Test HTML inscriptions before broadcasting.
Base64 HTML Preview
/preview/{base64EncodedHtml}
Example:
javascript
const html = "<html><body>Hello!</body></html>";
const b64 = btoa(html);
const previewUrl = `https://ordfs.network/preview/${b64}`;
POST Preview
bash
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
html
<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 |
|---|
| Latest block info |
| Block by height |
/v1/bsv/block/hash/{hash}
| Block by hash |
| Raw transaction |
V2 Endpoints
| Endpoint | Purpose |
|---|
| Raw transaction |
| Merkle proof |
| BEEF format proof |
| Specific output |
| Latest block header |
| Current height |
| Inscription metadata |
| Streaming content |
DNS-Based Access
Map custom domains to inscriptions.
DNS TXT Record
_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
typescript
// 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
typescript
// 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
typescript
// 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 () | 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
references/advanced-features.md
Examples
examples/fetch-content.ts
examples/recursive-inscription.html
Related Packages
- - URL normalization for ordfs.network
- - Create inscriptions
- - Inscription templates