obul-ordiscan

name	obul-ordiscan
description	USE THIS SKILL WHEN: the user wants to query Bitcoin Ordinals inscriptions, runes, BRC-20 balances, rare sats, or UTXOs. Provides pay-per-use Bitcoin data via Ordiscan through the Obul proxy.
homepage	https://ordiscan.com
metadata	{"obul-skill":{"emoji":"₿","requires":{"env":[],"primaryEnv":""}}}
registries	{}

Ordiscan

Ordiscan provides pay-per-request Bitcoin Ordinals and Runes data. Query inscriptions, rune balances, BRC-20 tokens, rare sats, and UTXOs by address. No API key needed — payment is handled automatically via obulx.

Authentication

All requests use the obulx CLI, which handles x402 payment automatically.

Common Operations

Get Inscription by ID

Retrieve details about a specific inscription by its ID.

Pricing: $0.01

Request:

obulx "https://api.ordiscan.com/v1/inscription/b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735i0"

Response: JSON with inscription details including content type, content URL, sat number, owner address, and genesis transaction.

Get Address Inscriptions

List all inscriptions owned by a Bitcoin address.

Pricing: $0.01

Request:

obulx "https://api.ordiscan.com/v1/address/bc1pxaneaf3w4d27hl2y93fuft2xk6m4u3wc4rafevc6slgd7f5tq2dqyfgy06/inscriptions"

Response: JSON array of inscription IDs and metadata owned by the address.

Get Address UTXOs

Retrieve UTXOs for a Bitcoin address with ordinals info.

Pricing: $0.01

Request:

obulx "https://api.ordiscan.com/v1/address/bc1pxaneaf3w4d27hl2y93fuft2xk6m4u3wc4rafevc6slgd7f5tq2dqyfgy06/utxos"

Response: JSON array of UTXOs with associated inscriptions and runes tied to each output.

Get Rune Balances

Retrieve rune balances for a Bitcoin address.

Pricing: $0.01

Request:

obulx "https://api.ordiscan.com/v1/address/bc1pxaneaf3w4d27hl2y93fuft2xk6m4u3wc4rafevc6slgd7f5tq2dqyfgy06/runes"

Response: JSON array of rune balances in the smallest denomination (no decimals).

Get BRC-20 Balances

Retrieve BRC-20 token balances for a Bitcoin address.

Pricing: $0.01

Request:

obulx "https://api.ordiscan.com/v1/address/bc1pxaneaf3w4d27hl2y93fuft2xk6m4u3wc4rafevc6slgd7f5tq2dqyfgy06/brc20"

Response: JSON array of BRC-20 token balances with ticker and amount.

Get Rare Sats

Find rare sats in a Bitcoin address.

Pricing: $0.01

Request:

obulx "https://api.ordiscan.com/v1/address/bc1pxaneaf3w4d27hl2y93fuft2xk6m4u3wc4rafevc6slgd7f5tq2dqyfgy06/rare-sats"

Response: JSON array of rare sats with rarity classification and sat number.

Get Inscription Transfers

Get inscription transfer history for a Bitcoin address.

Pricing: $0.01

Request:

obulx "https://api.ordiscan.com/v1/address/bc1pxaneaf3w4d27hl2y93fuft2xk6m4u3wc4rafevc6slgd7f5tq2dqyfgy06/transfers"

Response: JSON array of inscription transfers for the address.

Endpoint Pricing Reference

Endpoint	Price	Purpose
GET /v1/inscription/{id}	$0.01	Get inscription by ID
GET /v1/address/{address}/inscriptions	$0.01	List address inscriptions
GET /v1/address/{address}/utxos	$0.01	Get address UTXOs
GET /v1/address/{address}/runes	$0.01	Get rune balances
GET /v1/address/{address}/brc20	$0.01	Get BRC-20 balances
GET /v1/address/{address}/rare-sats	$0.01	Get rare sats
GET /v1/address/{address}/transfers	$0.01	Get inscription transfers

When to Use

• Ordinals lookup — User asks about Bitcoin Ordinals or inscriptions
• Inscription ownership — User wants to look up inscriptions owned by a Bitcoin address
• Rune balances — User asks about Runes token balances
• BRC-20 tokens — User asks about BRC-20 token balances
• Rare sats — User wants to find rare sats in a wallet
• Specific inscription — User asks about a specific inscription by ID
• UTXO data — User wants UTXO data for a Bitcoin address with ordinals info

Best Practices

• Address formats — Bitcoin addresses can be any format: P2PKH (1...), P2SH (3...), Bech32 (bc1q...), or Taproot (bc1p...)
• Rune denominations — Rune balances are returned in the smallest denomination and never have decimals
• Combine queries — Use UTXO endpoint to get comprehensive output data including inscriptions and runes

Notes

• All endpoints cost ~$0.01 USDC per request.
• The obulx CLI handles x402 payment automatically -- no USDC wallet or payment header needed.

Error Handling

Error	Cause	Solution
402 Payment Required	Payment not processed or insufficient	Verify your obulx setup is correct and your account has sufficient balance at my.obul.ai.
400 Bad Request	Invalid address format	Ensure the Bitcoin address is in a valid format.
404 Not Found	Address or inscription not found	Verify the address or inscription ID is correct.
429 Too Many Requests	Rate limit exceeded	Add a short delay between requests.
500 Internal Server Error	Ordiscan service issue	Wait a few seconds and retry. If persistent, the service may be experiencing downtime.