Ordiscan API

Inscribe content and query Ordinals data via the Ordiscan API. Every request is paid with USDC on Base using the x402 payment protocol -- no API key needed.

What this skill can do

• Inscribe content on Bitcoin -- text, images, HTML, SVG, and any other file type. The server builds and broadcasts the Bitcoin transactions for you. You only pay USDC on Base.
• Query Ordinals data -- look up inscriptions, addresses, runes, BRC-20 tokens, rare sats, and more.

Setup

Two payment modes are supported. Use the signing script by default. Only use awal if it's already installed and authenticated.

Default -- Signing script

Requires node and the X402_PRIVATE_KEY environment variable (an Ethereum private key with USDC on Base).

If X402_PRIVATE_KEY is not already set, check if ~/.evm-wallet.json exists (created by the evm-wallet skill). If it does, read the private key from it:

X402_PRIVATE_KEY=$(node -e "console.log(JSON.parse(require('fs').readFileSync(require('os').homedir()+'/.evm-wallet.json','utf8')).privateKey)")

If neither the env var nor the wallet file is available, suggest using the awal wallet.

# Install dependencies (only once)
npm install --prefix <skill-dir>

# Verify connectivity
X402_PRIVATE_KEY=$X402_PRIVATE_KEY node <skill-dir>/scripts/x402-sign.mjs balance

Alternative -- Coinbase Agentic Wallet (awal)

If awal is already installed and authenticated, it can be used instead. One command handles the full x402 negotiate-sign-pay flow.

# Check if awal is already available and authenticated
which awal && npx awal status

Making requests with signing script

This is a 3-step flow: request -> sign -> retry. The example below inscribes text, but the same pattern works for any endpoint.

Step 1: Send the request (get 402 + payment header)

CONTENT=$(echo -n "Hello from OpenClaw!" | base64)
BODY="{\"contentType\":\"text/plain\",\"base64_content\":\"$CONTENT\",\"recipientAddress\":\"bc1p...\"}"

HEADER=$(curl -s -o /tmp/x402_body.json -w '%header{Payment-Required}' \
  -X POST -H "Content-Type: application/json" \
  -d "$BODY" \
  "https://api.ordiscan.com/v1/inscribe")

Check the price before paying:

cat /tmp/x402_body.json

For GET requests (e.g. querying data), omit -X POST and -d.

Step 2: Sign the payment

PAYMENT=$(X402_PRIVATE_KEY=$X402_PRIVATE_KEY node <skill-dir>/scripts/x402-sign.mjs sign "$HEADER")

The script reads the base64-encoded Payment-Required header, signs an ERC-3009 TransferWithAuthorization, and outputs the base64-encoded Payment-Signature header to stdout. Diagnostics go to stderr.

Step 3: Retry with payment

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Payment-Signature: $PAYMENT" \
  -d "$BODY" \
  "https://api.ordiscan.com/v1/inscribe"

Making requests with awal

If awal is already available, it handles the full x402 flow in one command:

Querying data

npx awal x402 pay "https://api.ordiscan.com/v1/inscription/0"

Inscribing content

npx awal x402 pay "https://api.ordiscan.com/v1/inscribe" \
  --method POST \
  --data '{"contentType":"text/plain","base64_content":"SGVsbG8gd29ybGQ=","recipientAddress":"bc1p..."}' \
  --max-amount 5000000

The --max-amount flag caps the payment in USDC base units (6 decimals). 5000000 = $5.00 USDC.

Preparing content for inscription

When the user asks to inscribe something, follow these steps:

1. Determine the content and MIME type

• User provides text (e.g. "inscribe 'Hello world'"): use text/plain
• User provides a file path: detect the MIME type from the extension:

  Extension	Content type
  .txt	text/plain
  .html, .htm	text/html
  .svg	image/svg+xml
  .json	application/json
  .png	image/png
  .jpg, .jpeg	image/jpeg
  .gif	image/gif
  .webp	image/webp
  .mp3	audio/mpeg
  .mp4	video/mp4
  .pdf	application/pdf

2. Base64-encode the content

For text:

CONTENT=$(echo -n 'Hello world' | base64)

For a file:

CONTENT=$(base64 -w0 path/to/file)

-w0 disables line wrapping (important -- the API expects a single unbroken base64 string). On macOS, base64 doesn't wrap by default, so -w0 can be omitted.

3. Get the recipient Bitcoin address

Ask the user for their Bitcoin address if not already provided. This is the address that will own the inscription.

4. Call the inscribe endpoint

See the worked examples below.

Inscribe endpoint (deep dive)

POST /v1/inscribe creates a Bitcoin inscription. The server builds and broadcasts the commit + reveal transactions.

Request body

402 response (no payment)

When called without payment, the server returns 402 with dynamic pricing:

{
  "error": { "message": "Payment required..." },
  "priceUsdc": 1.23,
  "totalSats": 4567,
  "feeRate": 12,
  "btcPriceUsd": 100000
}

The Payment-Required header contains the base64-encoded x402 v2 payment details.

Use the 3-step signing script flow above to handle this. If using awal, it handles the 402 flow automatically.

Success response (200)

{
  "data": {
    "commitTxid": "abc123...",
    "revealTxid": "def456...",
    "inscriptionId": "def456...i0"
  }
}

After a successful inscription, always show the user a link to their inscription: https://ordiscan.com/inscription/{inscriptionId}

Worked example with signing script

CONTENT=$(echo -n "Hello Bitcoin!" | base64)
BODY="{\"contentType\":\"text/plain\",\"base64_content\":\"$CONTENT\",\"recipientAddress\":\"bc1p...\"}"

# Step 1: Get price and payment header
HEADER=$(curl -s -o /tmp/x402_body.json -w '%header{Payment-Required}' \
  -X POST -H "Content-Type: application/json" \
  -d "$BODY" \
  "https://api.ordiscan.com/v1/inscribe")

# Check the price
cat /tmp/x402_body.json

# Step 2: Sign
PAYMENT=$(X402_PRIVATE_KEY=$X402_PRIVATE_KEY node <skill-dir>/scripts/x402-sign.mjs sign "$HEADER")

# Step 3: Send with payment
curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Payment-Signature: $PAYMENT" \
  -d "$BODY" \
  "https://api.ordiscan.com/v1/inscribe"

Worked example with awal

CONTENT=$(echo -n "Hello Bitcoin!" | base64)

npx awal x402 pay "https://api.ordiscan.com/v1/inscribe" \
  --method POST \
  --data "{\"contentType\":\"text/plain\",\"base64_content\":\"$CONTENT\",\"recipientAddress\":\"bc1p...\"}" \
  --max-amount 5000000

Inscribing images

CONTENT=$(base64 -w0 image.png)

npx awal x402 pay "https://api.ordiscan.com/v1/inscribe" \
  --method POST \
  --data "{\"contentType\":\"image/png\",\"base64_content\":\"$CONTENT\",\"recipientAddress\":\"bc1p...\"}" \
  --max-amount 10000000

Inscribing HTML

CONTENT=$(echo -n '<html><body><h1>On-chain page</h1></body></html>' | base64)

npx awal x402 pay "https://api.ordiscan.com/v1/inscribe" \
  --method POST \
  --data "{\"contentType\":\"text/html\",\"base64_content\":\"$CONTENT\",\"recipientAddress\":\"bc1p...\"}" \
  --max-amount 5000000

API endpoint reference

See the Ordiscan API documentation

Response format

Success:

{ "data": { ... } }

Error:

{ "error": { "message": "..." } }

Error handling

Tips

• Payment mode: Use the signing script with X402_PRIVATE_KEY by default. Only use awal if it's already installed and authenticated (which awal succeeds).
• GET requests cost ~$0.01 USDC each. Inscription requests vary based on content size and Bitcoin fee rates.
• For inscriptions, always check the 402 response to see the price before paying. The priceUsdc field tells you the exact cost.
• Content limit is 400KB (decoded). For images, keep them reasonable in size.
• The inscribe endpoint returns commitTxid and revealTxid. Track them on https://mempool.space/tx/{txid} or https://ordiscan.com/inscription/{inscriptionId}.

External endpoints

All requests are paid via x402 (USDC on Base). Payment is handled by awal or the signing script.

Security & Privacy

• All data is sent to api.ordiscan.com over HTTPS.
• GET requests send only query parameters (inscription IDs, addresses, etc.).
• Inscription requests send the content you want to inscribe (base64-encoded) and a recipient Bitcoin address. This content is published on the Bitcoin blockchain and is permanently public.
• Mode A (awal): No credentials are read beyond what awal manages for x402 payments. No data is stored locally.
• Mode B (signing script): Reads X402_PRIVATE_KEY from the environment to sign USDC payments on Base. The private key is never sent over the network -- only the resulting EIP-3009 signature is transmitted. No data is stored locally.

By using this skill, your requests and inscription content are sent to Ordiscan. Only install if you trust Ordiscan.