# ORDnet MCP Server — Agent Skill

> **You are reading the skill file for https://mcp.ordnet.io — a public Model Context Protocol (MCP) server that lets AI agents hold wallets, inscribe permanent content and manage .web3 domains on the Bitcoin SV (BSV) blockchain, served by ORDnet's own nodes.**

## Connect

- **Endpoint:** `https://mcp.ordnet.io/mcp` (MCP Streamable HTTP transport, POST)
- **Authentication:** REQUIRED — send `Authorization: Bearer <token>` on every request. Without a valid token the server returns `401 Unauthorized`. Access on request: api@ordnet.io
- **Health:** `GET https://mcp.ordnet.io/health` (public, no token)
- **Protocol:** initialize -> notifications/initialized -> tools/list -> tools/call

Example MCP client configuration:

```json
{
  "mcpServers": {
    "ordnet": {
      "type": "http",
      "url": "https://mcp.ordnet.io/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}
```

Raw JSON-RPC example (any HTTP client):

```bash
curl -s -X POST https://mcp.ordnet.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'
```

## Recommended flow for a new agent

1. `ordnet_info` — read server capabilities and fees.
2. `ordnet_generate_wallet` or `ordnet_wallet_init` — create or load your wallet. **Fund it with a small amount of BSV.**
3. `ordnet_policy_set` — set your own spend limits BEFORE transacting (safety first).
4. `ordnet_fee_estimate` + `ordnet_inscribe_prepare` — build your inscription.
5. `ordnet_tx_simulate` — dry-run the raw transaction on ORDnet's own node. Nothing is broadcast.
6. `ordnet_inscribe_broadcast` — broadcast via ORDnet's own BSV node.
7. `ordnet_domain_check` + `ordnet_domain_register` — claim your .web3 identity.

## Safety model (read this)

- **Dry-run first:** `ordnet_tx_simulate` decodes any raw transaction on ORDnet's own node and returns destinations, amounts and warnings without broadcasting.
- **Spend policies:** `ordnet_policy_set` enforces per-transaction and per-session satoshi limits. When a limit is set, every broadcast is simulated first and BLOCKED if it exceeds a limit (fail-closed).
- **Ordinal awareness:** 1-satoshi outputs are flagged as likely inscriptions so you do not burn artifacts as miner fees.
- **Own settlement rail:** broadcasts go through ORDnet's own BSV node; public explorers are a fallback, never the authority.

---

# Tool Reference (45 tools)


## Wallet

### `ordnet_wallet_init`

Initialize wallet from WIF private key for blockchain operations.

This is the first step before creating inscriptions. The wallet will be used for:
- Creating and signing inscription transactions
- Paying service fees (2775 sats to 1EXupec98g8TDTG5cwJwH3U8V3PezvvLv8)
- Receiving change from transactions

Security: WIF is held in memory only, not persisted. Use ordnet_wallet_init_env for production.

Args:
  - wif (string): WIF private key (starts with 5, K, or L, 51-52 chars)

Returns:
  { address: string, publicKey: string, balanceSatoshis: number }

Example:
  ordnet_wallet_init({ wif: "L1a2b3c4d5..." }) → Wallet initialized at 1ABC...

**Parameters:**

- `wif` (string, **required**) — WIF (Wallet Import Format) private key. Starts with 5, K, or L.

### `ordnet_wallet_init_env`

Initialize wallet from environment variable (highest security tier).

Reads WIF from environment variable instead of passing it directly.
Recommended for production use.

Args:
  - envVarName (string): Environment variable name (default: ORDNET_WIF)

Returns:
  { address: string, balanceSatoshis: number }

Example:
  export ORDNET_WIF="L1a2b3c4..."
  ordnet_wallet_init_env({}) → Wallet initialized

**Parameters:**

- `envVarName` (string, optional) — Environment variable name containing the WIF (default: ORDNET_WIF)

### `ordnet_wallet_status`

Check current wallet initialization status and balance.

Returns wallet address and balance if initialized.

Returns:
  { initialized: boolean, address?: string, balanceSatoshis?: number }

**Parameters:**

_No parameters._

### `ordnet_wallet_balance`

Get balance for any BSV address.

Args:
  - address (string, optional): BSV address. Uses wallet address if not provided.

Returns:
  { address: string, confirmed: number, unconfirmed: number, total: number }

**Parameters:**

- `address` (string, optional) — BSV address to check. If not provided, uses the initialized wallet address.

### `ordnet_wallet_utxos`

Get unspent transaction outputs (UTXOs) for an address.

Args:
  - address (string, optional): BSV address. Uses wallet address if not provided.
  - limit (number): Maximum UTXOs to return (default: 5)

Returns:
  { utxos: [{ txid, vout, satoshis }], count: number }

**Parameters:**

- `address` (string, optional) — BSV address to get UTXOs for. If not provided, uses the initialized wallet address.
- `limit` (integer, optional) — Maximum number of UTXOs to return (default: 5)

### `ordnet_wallet_clear`

Clear wallet from memory. Use when done with operations.

Returns:
  { cleared: true }

**Parameters:**

_No parameters._


## Inscriptions

### `ordnet_fee_estimate`

Calculate fee estimate for an inscription.

Service fees breakdown:
- Builders fee: 111 sats
- Protocol fee: 222 sats
- Monitor fee: 333 sats
- Indexer fee: 444 sats
- Creator fee: 777 sats
- Foundation fee: 888 sats
- Total: 2775 sats

Args:
  - contentSize (number): Size of content in bytes
  - feePerByte (number): Fee per byte (default: 0.2 = 200 sats/KB)

Returns:
  { estimatedTxSize, minerFee, serviceFee, totalCost, breakdown }

**Parameters:**

- `contentSize` (integer, **required**) — Size of the content to inscribe in bytes
- `feePerByte` (number, optional) — Fee per byte in satoshis (default: 0.2, minimum: 0.05)

### `ordnet_inscribe_prepare`

Prepare an inscription transaction without broadcasting.

Creates a signed transaction ready for broadcast. Returns the raw hex
and fee breakdown for review before broadcasting.

Args:
  - content (string): Content to inscribe (HTML, text, JSON, etc.)
  - contentType (string): MIME type (default: text/html;charset=utf8)
  - feePerByte (number): Fee per byte (default: 0.2)

Returns:
  { rawHex, txid, feeEstimate, inscriptionId }

Requires: Wallet must be initialized first.

**Parameters:**

- `content` (string, **required**) — The content to inscribe on the blockchain
- `contentType` (string, optional) — MIME content type (default: text/html;charset=utf8)
- `feePerByte` (number, optional) — Fee per byte in satoshis (default: 0.2)

### `ordnet_inscribe_broadcast`

Broadcast a prepared inscription transaction to the BSV network.

WARNING: This action is IRREVERSIBLE. The transaction will be permanently
recorded on the blockchain.

Args:
  - rawHex (string): Raw transaction hex from ordnet_inscribe_prepare

Returns:
  { txid, inscriptionId, viewUrl, transactionUrl }

**Parameters:**

- `rawHex` (string, **required**) — Raw transaction hex to broadcast

### `ordnet_inscribe_html`

Create and broadcast an HTML inscription in one step.

Convenience tool that prepares and broadcasts an HTML inscription.

Args:
  - content (string): HTML content to inscribe
  - feePerByte (number): Fee per byte (default: 0.2)

Returns:
  { txid, inscriptionId, viewUrl }

Requires: Wallet must be initialized.

**Parameters:**

- `content` (string, **required**) — The content to inscribe on the blockchain
- `feePerByte` (number, optional) — Fee per byte in satoshis (default: 0.2)

### `ordnet_inscribe_json`

Create and broadcast a JSON inscription in one step.

Args:
  - content (string): JSON content to inscribe
  - feePerByte (number): Fee per byte (default: 0.2)

Returns:
  { txid, inscriptionId, viewUrl }

**Parameters:**

- `content` (string, **required**) — The content to inscribe on the blockchain
- `feePerByte` (number, optional) — Fee per byte in satoshis (default: 0.2)

### `ordnet_inscribe_text`

Create and broadcast a plain text inscription in one step.

Args:
  - content (string): Text content to inscribe
  - feePerByte (number): Fee per byte (default: 0.2)

Returns:
  { txid, inscriptionId, viewUrl }

**Parameters:**

- `content` (string, **required**) — The content to inscribe on the blockchain
- `feePerByte` (number, optional) — Fee per byte in satoshis (default: 0.2)


### `ordnet_inscribe_binary`
Prepare an inscription for BINARY content (images, audio, video, PDF) from base64.
**Parameters:**
- `contentBase64` (string, **required**) — Base64-encoded binary content
- `contentType` (string, **required**) — MIME type
- `feePerByte` (number, optional) — Fee per byte (default 0.15)

### `ordnet_bsvmap_inscribe`
Claim a BSVmap tile by inscribing "<tile>.bsvmap" (text/plain).
**Parameters:**
- `tile` (number, **required**) — BSVmap tile number (0-999999)
- `feePerByte` (number, optional) — Fee per byte (default 0.15)

## Domains

### `ordnet_domain_check`

Check if a domain name is available for registration.

Args:
  - name (string): Domain name without extension (e.g., "myname")
  - extension (string): Domain extension (default: .sats)

Returns:
  { available: boolean, owner?: string, inscriptionId?: string }

**Parameters:**

- `name` (string, **required**) — Domain name to check (without extension, e.g., "myname")
- `extension` (string, optional) — Domain extension (default: .sats)

### `ordnet_domain_info`

Get detailed information about a domain.

Args:
  - fullName (string): Full domain name (e.g., "myname.sats")

Returns:
  { name, extension, owner, inscriptionId, genesisHeight, protocol }

**Parameters:**

- `fullName` (string, **required**) — Full domain name including extension (e.g., "myname.sats")

### `ordnet_domain_search`

Search for registered domains by name prefix.

Args:
  - query (string): Search query
  - limit (number): Maximum results (default: 20)

Returns:
  { domains: [{ name, owner, inscriptionId }], count }

**Parameters:**

- `query` (string, **required**) — Search query for domain names
- `limit` (integer, optional) — Maximum results to return (default: 20)

### `ordnet_domain_register`

Register a new SNS/OPNS domain on the blockchain.

Creates and broadcasts a domain registration inscription.

Args:
  - name (string): Domain name without extension
  - extension (string): Domain extension (default: .sats)
  - protocol (string): Registration protocol: sns or opns (default: sns)
  - feePerByte (number): Fee per byte (default: 0.2)

Returns:
  { txid, inscriptionId, domain }

Requires: Wallet must be initialized.

**Parameters:**

- `name` (string, **required**) — Domain name to register (without extension)
- `extension` (string, optional) — Domain extension (default: .sats)
- `protocol` (string, optional) — Registration protocol: sns or opns (default: sns)
- `feePerByte` (number, optional) — Fee per byte in satoshis

### `ordnet_domain_register_sns`

Quick registration of an SNS domain (.sats, .btc, etc).

Args:
  - name (string): Domain name without extension
  - extension (string): Extension (default: .sats)
  - feePerByte (number): Fee per byte (default: 0.2)

Returns:
  { txid, inscriptionId, domain }

**Parameters:**

- `name` (string, **required**) — Domain name to register (without extension)
- `extension` (string, optional) — Domain extension (default: .sats)
- `feePerByte` (number, optional) — Fee per byte in satoshis

### `ordnet_domain_register_opns`

Quick registration of an OPNS domain.

Args:
  - name (string): Domain name without extension
  - extension (string): Extension (default: .sats)
  - feePerByte (number): Fee per byte (default: 0.2)

Returns:
  { txid, inscriptionId, domain }

**Parameters:**

- `name` (string, **required**) — Domain name to register (without extension)
- `extension` (string, optional) — Domain extension (default: .sats)
- `feePerByte` (number, optional) — Fee per byte in satoshis


## Search & Content

### `ordnet_search_inscriptions`

Search for inscriptions on the BSV blockchain.

Args:
  - query (string): Search query
  - contentType (string, optional): Filter by content type
  - limit (number): Maximum results (default: 20)

Returns:
  { inscriptions: [...], count }

**Parameters:**

- `query` (string, **required**) — Search query
- `contentType` (string, optional) — Filter by content type (e.g., "text/html")
- `limit` (integer, optional) — Maximum results to return (default: 20)

### `ordnet_get_inscription`

Get detailed information about a specific inscription.

Args:
  - inscriptionId (string): Inscription ID (format: txid_outputIndex)

Returns:
  { inscriptionId, contentType, contentSize, owner, ... }

**Parameters:**

- `inscriptionId` (string, **required**) — Inscription ID in format: txid_outputIndex

### `ordnet_get_content_url`

Get the URL to view inscription content.

Args:
  - inscriptionId (string): Inscription ID

Returns:
  { inscriptionId, contentUrl, viewUrl, transactionUrl }

**Parameters:**

- `inscriptionId` (string, **required**) — Inscription ID in format: txid_outputIndex

### `ordnet_content_types`

Get list of all supported content types for inscriptions.

Returns:
  { contentTypes: [...] }

**Parameters:**

_No parameters._


## Security

### `ordnet_security_encrypt_wallet`

Encrypt a WIF private key with AES-256-GCM.

Use this to create an encrypted wallet that can be stored safely.
The encrypted data can later be decrypted with ordnet_wallet_init with the password.

Args:
  - wif (string): WIF private key to encrypt
  - password (string): Strong password (min 12 chars)

Returns:
  { encrypted: { iv, data, tag, salt } }

**Parameters:**

- `wif` (string, **required**) — WIF private key to encrypt
- `password` (string, **required**) — Strong password for encryption

### `ordnet_security_tier`

Check the current wallet security tier.

Tiers (highest to lowest):
1. environment - WIF from environment variable
2. encrypted - WIF from encrypted store
3. plaintext - WIF provided directly (not recommended)

Returns:
  { tier, envVarSet, recommendation }

**Parameters:**

_No parameters._

### `ordnet_security_validate_password`

Check if a password meets security requirements.

Requirements:
- Minimum 12 characters
- At least one uppercase letter
- At least one lowercase letter
- At least one number
- At least one special character

Args:
  - password (string): Password to validate

Returns:
  { valid: boolean, errors: string[] }

**Parameters:**

- `password` (string, **required**) — Password to validate

### `ordnet_generate_wallet`

Generate a new random BSV wallet.

WARNING: Store the WIF securely! It cannot be recovered if lost.

Returns:
  { wif, address }

**Parameters:**

_No parameters._


## Safety (Agent Protection)

### `ordnet_tx_simulate`

Decode and inspect a raw transaction via ORDnet's OWN node WITHOUT broadcasting it.

Use this BEFORE ordnet_inscribe_broadcast to verify exactly what a transaction
will do: destinations, amounts, and safety warnings (e.g. 1-satoshi outputs
that are likely ordinals/inscriptions).

Args:
  - rawHex (string): Raw transaction hex to simulate

Returns:
  { txid, sizeBytes, outputCount, totalOutputSats, outputs[], warnings[] }

**Parameters:**

- `rawHex` (string, **required**) — Raw transaction hex to simulate (dry-run decode, nothing is broadcast)

### `ordnet_policy_set`

Configure spend limits for this server session (agent safety layer).

When any limit is set, every broadcast is first simulated via ORDnet's own
node and BLOCKED if it would exceed a limit (fail-closed). When no limits
are set, broadcasts behave exactly as before.

Limits apply to the TOTAL output value of a transaction, including change
back to the agent's own wallet (a conservative upper bound).

Args:
  - maxSatsPerTx (number|null, optional): Max output sats per transaction; null removes the limit
  - maxSatsPerSession (number|null, optional): Max cumulative output sats this session; null removes the limit
  - resetSession (boolean, optional): Reset the session spend counter

Returns:
  The active policy after applying changes.

**Parameters:**

- `maxSatsPerTx` (any, optional) — Max total output sats per transaction. null = remove limit. Omit = keep current.
- `maxSatsPerSession` (any, optional) — Max cumulative output sats this session. null = remove limit. Omit = keep current.
- `resetSession` (boolean, optional) — Reset the session spend counter to zero

### `ordnet_policy_status`

Show the active spend policy and session totals.

Returns:
  { maxSatsPerTx, maxSatsPerSession, spentThisSession, broadcastCount }

**Parameters:**

_No parameters._


## UTXO Index

Since v2.5 balance and UTXO lookups are served by ORDnet's own address index
(ordnet-utxo): every UTXO is individually verified by ORDnet's own BSV node.
WhatsOnChain is only a connectivity fallback.

### `ordnet_index_health`

Check the health and sync status of ORDnet's own address/UTXO index.

Returns:
  { status, index_height, node_height, in_sync }

**Parameters:**

_No parameters._

### `ordnet_address_watch`

Register a BSV address in the index watchlist. The index seeds it immediately
(every UTXO node-verified) and then tracks it in real time — pre-register so
an agent's first balance query is instant. Unknown addresses are also
auto-registered on their first balance/UTXO query.

**Parameters:**

- `address` (string, **required**) — BSV address to watch
- `label` (string, optional) — Label for the watchlist entry (default: "mcp")


## Payments

### `ordnet_send`
Send a plain BSV payment (P2PKH) from the initialized wallet, with optional OP_RETURN.
**Parameters:**
- `to` (string, **required**) — Recipient BSV address
- `satoshis` (number, **required**) — Amount in satoshis
- `opReturn` (string, optional) — Optional OP_RETURN data (e.g. an x402 reference)

### `ordnet_transfer`
Transfer an inscription (ordinal, .web3/SNS/OPNS domain, BSVmap tile) to another address.
**Parameters:**
- `inscriptionTxid` (string, **required**) — Txid of the inscription outpoint
- `inscriptionVout` (number, **required**) — Output index (usually 0)
- `to` (string, **required**) — Recipient BSV address

### `ordnet_tx_status`
Check the status and confirmations of a transaction via ORDnet's own node.
**Parameters:**
- `txid` (string, **required**) — Transaction ID to check

### `ordnet_price`
Get the current BSV price in fiat, via ORDnet's own CoinGecko proxy.
**Parameters:**
- `currencies` (string, optional) — Comma-separated fiat currencies (default: usd,eur)

## Identity — BRC-100

### `ordnet_identity`
Return the wallet's BRC-100 identity: its public key and address.
**Parameters:** _No parameters._

### `ordnet_sign_message`
Sign an arbitrary message with the wallet's private key (BRC-100 createSignature).
**Parameters:**
- `message` (string, **required**) — Message to sign

### `ordnet_verify_message`
Verify a signature against a message and public key (BRC-100 verifySignature).
**Parameters:**
- `message` (string, **required**) — Original message
- `signature` (string, **required**) — Signature to verify
- `publicKey` (string, **required**) — Signer public key

### `ordnet_derive_payment_address`
Derive a unique, deterministic payment address for an invoice/reference (BRC-42/29).
**Parameters:**
- `invoiceId` (string, **required**) — Invoice or reference string

## x402 Client

### `ordnet_x402_quote`
Inspect an x402-paywalled URL WITHOUT paying: returns price, payTo, and requirements. Read-only.
**Parameters:**
- `url` (string, **required**) — Resource URL
- `method` (string, optional) — GET or POST (default GET)

### `ordnet_x402_fetch`
Consume an x402-paywalled resource in one call: detect 402, pay in native sats, retry with proof, return resource + receipt. Refuses quotes above maxSats.
**Parameters:**
- `url` (string, **required**) — Resource URL
- `method` (string, optional) — GET or POST (default GET)
- `maxSats` (number, **required**) — Spending guard in satoshis

## Utilities

### `ordnet_info`

Get information about the ORDnet MCP server.

Returns server version, capabilities, and service fee information.

**Parameters:**

_No parameters._

### `ordnet_validate_address`

Validate a BSV address format.

Args:
  - address (string): BSV address to validate

Returns:
  { valid: boolean, address }

**Parameters:**

- `address` (string, **required**) — BSV address to validate

---

## Ecosystem

- Registry & marketplace: https://domains.ordnet.io
- Search: https://search.ordnet.io
- Multi-chain node API (11 chains): https://api.ordnet.io
- OpenClaw web3 hosting skill: https://clawdbot.ordnet.io/skill.md
- Main site: https://ordnet.io

(c) ORDnet.io — Mister HHC B.V.