Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Sochain Com Blocks API
version: '3'
description: 'Operations tagged Blocks across 3 of this provider''s published API definitions: sochain-com-openapi.json, dev-sochain-com-openapi.json, sochain-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://sochain.com/api/v3
- url: https://dev.sochain.com/api/v3
security:
- ApiKey: []
- ApiKeyQuery: []
tags:
- name: Blocks
paths:
/block/{network}/{hash_or_height}:
get:
operationId: get_block
tags:
- Blocks
summary: One block, by height or hash
description: Header, subsidy (reward), fees, value out and every transaction ID.
parameters:
- $ref: '#/components/parameters/network'
- $ref: '#/components/parameters/hash_or_height'
- $ref: '#/components/parameters/currency'
security:
- {}
- ApiKey: []
- ApiKeyQuery: []
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
required:
- status
- data
properties:
status:
const: success
data:
$ref: '#/components/schemas/Block'
example:
status: success
data:
height: 769784
time: 1672527188
confirmations: 199326
num_txs: 3129
version: 806608896
nonce: 1540456790
size: 1455151
weight: 3992836
hash: 00000000000000000002c8e5b14ba637c797b77d38eb47e633e57f424e6862e4
previous_block_hash: 0000000000000000000702f415a7e5a739d9a4b82dcd171a1f25df3110907ed1
next_block_hash: 00000000000000000007e61a3f241d9b22fbb6166ef7de4807fedd40550b21d9
is_orphan: false
difficulty: '35364065900457.12'
merkleroot: 0b4e0878982a60cbd108baaf9865ca37031c0debc3fc125d05322318f7dd9dc7
reward: '6.25000000'
fees: '0.15156792'
value_out: '8165.72847929'
bits: 1707f590
txs:
- 8ef8cecb5e394c40962f02ed2a7f8a3cf027365484860acc0aeed93477493698
- c5b88570a35b81842bcc2f35ee82bb4bd4bd09d4ee836adae60c4010d1903dfa
- 477f4d5d56a704ac550474dd0a9735351c6d225254f00ecd1dc38ee7297f34d8
price:
value: '16603.67470264'
currency: USD
median_time: 1672524293
chainwork: 00000000000000000000000000000000000000003cb18ce557a10dbacb684b0e
stripped_size: 845895
auxpow: null
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: 'Not found: an unknown network, or an argument the network doesn''t know.'
content:
application/json:
schema:
$ref: '#/components/schemas/Fail'
examples:
legacy:
summary: This endpoint's message
value:
status: fail
data:
error_message: Unable to fetch block data. Invalid block height or blockhash?
network:
summary: Unknown network code
value:
status: fail
data:
error_message: Unsupported network. Use BTC, LTC, DOGE, ZEC, BTCTEST, LTCTEST, DOGETEST or ZECTEST.
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/Unavailable'
externalDocs:
url: https://sochain.com/docs/block
servers:
- url: https://sochain.com/api/v3
/latest_blocks_summary/{network}:
get:
operationId: get_latest_blocks
tags:
- Blocks
summary: The last ten blocks
description: Newest first, with miner address and reward plus fees.
parameters:
- $ref: '#/components/parameters/network'
- $ref: '#/components/parameters/currency'
security:
- {}
- ApiKey: []
- ApiKeyQuery: []
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
required:
- status
- data
properties:
status:
const: success
data:
$ref: '#/components/schemas/LatestBlocks'
example:
status: success
data:
blocks:
- height: 969109
time: 1790662458
num_txs: 88
size: 59417
weight: 134138
version: 711319552
difficulty: '132757073449487.5'
price:
value: '83462.70000000'
currency: USD
miner: 3J1zSHERKN7FgsEjHeTcwG9tYE3GuMWTcM
reward_and_fees: '3.12608177'
- height: 969108
time: 1790662420
num_txs: 5397
size: 1571130
weight: 3993099
version: 663683072
difficulty: '132757073449487.5'
price:
value: '83462.70000000'
currency: USD
miner: bc1qtm7ye0wm085hhv88japwkalmwkt3amec5z9c7a3unv05tfg6y2pstr3xfz
reward_and_fees: '3.13667844'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: 'Not found: an unknown network, or an argument the network doesn''t know.'
content:
application/json:
schema:
$ref: '#/components/schemas/Fail'
examples:
legacy:
summary: This endpoint's message
value:
status: fail
data:
error_message: Unable to fetch latest blocks' summary. Try again in a few minutes.
network:
summary: Unknown network code
value:
status: fail
data:
error_message: Unsupported network. Use BTC, LTC, DOGE, ZEC, BTCTEST, LTCTEST, DOGETEST or ZECTEST.
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/Unavailable'
externalDocs:
url: https://sochain.com/docs/latest_blocks_summary
servers:
- url: https://sochain.com/api/v3
/best_block_hash/{network}:
get:
operationId: get_best_block_hash
tags:
- Blocks
summary: Hash of the newest block
description: The cheapest way to notice a new block.
parameters:
- $ref: '#/components/parameters/network'
security:
- {}
- ApiKey: []
- ApiKeyQuery: []
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
required:
- status
- data
properties:
status:
const: success
data:
$ref: '#/components/schemas/BestBlockHash'
example:
status: success
data:
hash: 000000000000000000000474eca618c25628bef0c45f29aaea93af7a28384413
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: 'Not found: an unknown network, or an argument the network doesn''t know.'
content:
application/json:
schema:
$ref: '#/components/schemas/Fail'
examples:
legacy:
summary: This endpoint's message
value:
status: fail
data:
error_message: Unable to fetch latest block hash. Try again in a few minutes.
network:
summary: Unknown network code
value:
status: fail
data:
error_message: Unsupported network. Use BTC, LTC, DOGE, ZEC, BTCTEST, LTCTEST, DOGETEST or ZECTEST.
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/Unavailable'
externalDocs:
url: https://sochain.com/docs/best_block_hash
servers:
- url: https://sochain.com/api/v3
components:
responses:
Unauthorized:
description: An invalid key, no key where one is needed (buckets, webhooks, /account_info), a locked account or expired plan, or both the month's requests and the keyless rate used up. Kept as 401, with this message, for v3 compatibility.
content:
application/json:
schema:
$ref: '#/components/schemas/Fail'
example:
status: fail
data:
error_message: API Key invalid, account access expired, or this account's daily request limit has been exhausted.
BadRequest:
description: A bad parameter or body; the message says which.
content:
application/json:
schema:
$ref: '#/components/schemas/Fail'
Unavailable:
description: Briefly unavailable; retry with backoff. May carry Retry-After.
content:
application/json:
schema:
$ref: '#/components/schemas/Fail'
example:
status: fail
data:
error_message: Temporarily unavailable. Try again in a few minutes.
TooManyRequests:
description: 'Without a key, past the day''s 2,500 lookups from this IP while SoChain is busy (Retry-After: 60), or past the day''s most (Retry-After: seconds to 00:00 UTC). With or without one, too many requests in flight at once (Retry-After: 1, not counted).'
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait.
content:
application/json:
schema:
$ref: '#/components/schemas/Fail'
example:
status: fail
data:
error_message: 'Lookups without a key are 2,500 a day per IP, and today''s are used up; they reset at 00:00 UTC. A free API key gives you 75,000 a month: https://sochain.com/signin?from=limit'
TooManyRequests_2:
description: 'Without a key, past the day''s 2,500 lookups from this IP while SoChain is busy (Retry-After: 60), or past the day''s most (Retry-After: seconds to 00:00 UTC). With or without one, too many requests in flight at once (Retry-After: 1, not counted).'
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait.
content:
application/json:
schema:
$ref: '#/components/schemas/Fail'
example:
status: fail
data:
error_message: 'Lookups without a key are 2,500 a day per IP, and today''s are used up; they reset at 00:00 UTC. A free API key gives you 75,000 a month: https://dev.sochain.com/signin?from=limit'
schemas:
BlockKinds:
type:
- object
- 'null'
description: 'A block''s transactions by kind, each by name. Every transaction counts, under one kind, except the coinbase (and Litecoin''s HogEx); a kind with none is left out. null or absent for a block whose kinds aren''t known yet. coinjoin, a cooperative lightning_close and a fee_bumped child paying its parent''s fee are told by their shape alone: likely, not certain.'
properties:
payment:
$ref: '#/components/schemas/KindTotals'
description: An ordinary payment, and anything that isn't another kind. BTC, LTC, DOGE.
batch_payout:
$ref: '#/components/schemas/KindTotals'
description: 'One sender paying many at once: exchanges, payroll. BTC, LTC, DOGE.'
consolidation:
$ref: '#/components/schemas/KindTotals'
description: Many coins merged into one or two, often while fees are low. BTC, LTC, DOGE.
coinjoin:
$ref: '#/components/schemas/KindTotals'
description: Many people mixing equal amounts. BTC, LTC.
inscription:
$ref: '#/components/schemas/KindTotals'
description: 'Content, such as an image or text, inscribed on chain: ordinals and Atomicals, and Doginals on Dogecoin. BTC, LTC, DOGE.'
data:
$ref: '#/components/schemas/KindTotals'
description: 'Records in OP_RETURN outputs: timestamps, proofs. BTC, LTC, DOGE.'
lightning_close:
$ref: '#/components/schemas/KindTotals'
description: A Lightning channel closing. BTC, LTC.
fee_bumped:
$ref: '#/components/schemas/KindTotals'
description: A replacement paying more to get in sooner, or a child paying its parent's fee. BTC, LTC, DOGE.
mweb_peg_in:
$ref: '#/components/schemas/KindTotals'
description: Coins moving into Litecoin's MWEB extension block. LTC.
large_script:
$ref: '#/components/schemas/KindTotals'
description: A big input script that isn't a multisig spend, usually carrying data. DOGE.
transparent:
$ref: '#/components/schemas/KindTotals'
description: 'Visible senders, receivers and amounts: no shielded parts. ZEC.'
shielding:
$ref: '#/components/schemas/KindTotals'
description: Coins moving from transparent inputs into a shielded pool. ZEC.
deshielding:
$ref: '#/components/schemas/KindTotals'
description: Coins leaving a shielded pool for transparent outputs. ZEC.
shielded:
$ref: '#/components/schemas/KindTotals'
description: 'Fully private: no transparent inputs or outputs. ZEC.'
rune:
$ref: '#/components/schemas/KindTotals'
description: 'Runes tokens etched, minted or moved: a runestone, or Alkanes; Dunes on Dogecoin. BTC, LTC, DOGE.'
bridge:
$ref: '#/components/schemas/KindTotals'
description: 'Coins crossing to or from another chain: a bridge, or a cross-chain swap. BTC, LTC, DOGE, ZEC.'
token:
$ref: '#/components/schemas/KindTotals'
description: 'Tokens on an older protocol issued or moved: Counterparty, Stamps (SRC-20), Omni; OmniLite on Litecoin. BTC, LTC.'
staking:
$ref: '#/components/schemas/KindTotals'
description: 'Bitcoin staked, unstaked or slashed: Babylon, Core DAO, Stacks stacking. BTC.'
anchoring:
$ref: '#/components/schemas/KindTotals'
description: 'Another chain''s checkpoint written into Bitcoin: Stacks block commits, Hemi, Babylon. BTC.'
other:
$ref: '#/components/schemas/KindTotals'
description: A kind added later, until it's named here.
additionalProperties:
$ref: '#/components/schemas/KindTotals'
KindTotals:
type: object
required:
- num_txs
- vsize
- fees
properties:
num_txs:
type: integer
description: How many transactions.
vsize:
type: integer
description: Their virtual size in vbytes (bytes on DOGE and ZEC).
fees:
oneOf:
- $ref: '#/components/schemas/Amount'
- type: 'null'
description: The fees they paid, in coins; null where they can't be known (as for mweb_peg_in).
BestBlockHash:
type: object
required:
- hash
properties:
hash:
type: string
Price:
type: object
required:
- value
- currency
description: 'Price per coin, 8 decimals: in US dollars, or in the currency asked for. Always 0.00000000 on testnets.'
properties:
value:
$ref: '#/components/schemas/Amount'
currency:
type: string
description: USD, or the currency asked for.
LatestBlock:
type: object
required:
- height
- time
- num_txs
- size
- weight
- version
- difficulty
- price
- miner
- reward_and_fees
properties:
height:
type: integer
time:
type: integer
num_txs:
type: integer
size:
type: integer
weight:
type: integer
version:
type: integer
difficulty:
type: string
price:
anyOf:
- $ref: '#/components/schemas/Price'
- type: 'null'
description: 'The price at the time, as Price; null where there''s no price: before the network''s price history (Bitcoin''s starts 13 Jul 2010), or a block stamped ahead of the clock. Testnets: always 0.'
miner:
type:
- string
- 'null'
description: Address paid by the coinbase, usually the pool's payout address.
reward_and_fees:
$ref: '#/components/schemas/Amount'
description: Subsidy plus fees.
kinds:
$ref: '#/components/schemas/BlockKinds'
Block:
type: object
required:
- height
- time
- confirmations
- num_txs
- version
- nonce
- size
- weight
- hash
- previous_block_hash
- next_block_hash
- is_orphan
- difficulty
- merkleroot
- reward
- fees
- value_out
- bits
- txs
- price
properties:
height:
type: integer
time:
type: integer
confirmations:
type: integer
num_txs:
type: integer
version:
type: integer
nonce:
type:
- integer
- string
description: 'The header''s nonce. On Zcash (ZEC, ZECTEST), a string: its 32-byte Equihash nonce in hex.'
size:
type: integer
weight:
type: integer
hash:
type: string
previous_block_hash:
type:
- string
- 'null'
description: Null for the genesis block.
next_block_hash:
type:
- string
- 'null'
description: Null for the newest block.
is_orphan:
type: boolean
difficulty:
type: string
merkleroot:
type: string
reward:
$ref: '#/components/schemas/Amount'
description: The block subsidy (fees not included).
fees:
$ref: '#/components/schemas/Amount'
min_fee_rate:
type:
- integer
- 'null'
description: 'The lowest fee rate its transactions paid, rounded up to a whole unit: sat/vB on BTC, lit/vB on LTC, koinu/vB on DOGE, zat/action on ZEC. The coinbase isn''t counted; on Litecoin, MWEB''s HogEx transaction, peg-ins and transactions spending MWEB coins aren''t either. Null for a block with only its coinbase.'
median_fee_rate:
type:
- integer
- 'null'
description: The median fee rate (with an even count, the lower of the two middle rates), in the same units and with the same exclusions as min_fee_rate.
max_fee_rate:
type:
- integer
- 'null'
description: The highest fee rate, in the same units and with the same exclusions as min_fee_rate.
min_fee_rate_precise:
type:
- string
- 'null'
description: min_fee_rate to two decimal places, not rounded up ("0.31"). Null where not available yet, which includes most blocks mined before 5 October 2026.
median_fee_rate_precise:
type:
- string
- 'null'
description: median_fee_rate to two decimal places; null as for min_fee_rate_precise.
max_fee_rate_precise:
type:
- string
- 'null'
description: max_fee_rate to two decimal places; null as for min_fee_rate_precise.
reward_split:
type: object
description: 'Zcash (ZEC) only: where the reward went. Amounts are decimal strings.'
properties:
subsidy:
type: string
fees:
type: string
miner_address:
type: string
miner_transparent:
type: string
miner_shielded:
type: string
funding_streams:
type: array
items:
type: object
properties:
recipient:
type: string
kind:
type: string
address:
type: string
value:
type: string
lockbox:
type: string
lockbox_disbursement:
type: string
unclaimed:
type: string
nsm_fee_contribution:
type: string
description: 'From the NU7 upgrade (ZEC from block 3,543,405, ZECTEST from 4,465,026): the 60% of fees burned into the NSM reserve; 0 before it.'
value_out:
$ref: '#/components/schemas/Amount'
bits:
type: string
description: Compact target, hex.
txs:
type: array
items:
type: string
description: Every transaction ID, in block order.
price:
anyOf:
- $ref: '#/components/schemas/Price'
- type: 'null'
description: 'The price at the time, as Price; null where there''s no price: before the network''s price history (Bitcoin''s starts 13 Jul 2010), or a block stamped ahead of the clock. Testnets: always 0.'
kinds:
$ref: '#/components/schemas/BlockKinds'
median_time:
type:
- integer
- 'null'
description: The median time of this block and the 10 before it (Unix time); null for an orphaned Zcash block.
chainwork:
type:
- string
- 'null'
description: The chain's total expected work up to this block, 64 hex characters; null on ZEC and ZECTEST.
stripped_size:
type:
- integer
- 'null'
description: Size without witness data, in bytes; null on DOGE, DOGETEST, ZEC and ZECTEST.
mweb:
type: object
description: Litecoin only, from MWEB's activation. value_out includes the pool carried over from block to block; subtract pool for the value the block moved.
properties:
pool:
$ref: '#/components/schemas/Amount'
pool_change:
anyOf:
- $ref: '#/components/schemas/Amount'
- type: 'null'
pegin:
$ref: '#/components/schemas/Amount'
pegin_count:
type: integer
pegout:
$ref: '#/components/schemas/Amount'
pegout_count:
type: integer
fees:
$ref: '#/components/schemas/Amount'
kernels:
type:
- integer
- 'null'
auxpow:
type:
- object
- 'null'
description: 'Dogecoin (DOGE, DOGETEST), a merge-mined block: the Litecoin block attempt whose proof of work it reuses. null on every other block.'
properties:
parent_hash:
type: string
description: 'The parent header''s hash: the Litecoin block hash it has, or would have had.'
parent_prev_hash:
type: string
description: The parent header's previous block.
parent_chain:
type:
- string
- 'null'
description: LTC (LTCTEST on DOGETEST) when the parent builds on a Litecoin block; null otherwise.
parent_in_chain:
type:
- boolean
- 'null'
description: Whether the attempt became a Litecoin block; null until that's known.
parent_height:
type:
- integer
- 'null'
description: Its Litecoin height, when parent_in_chain is true.
Fail:
type: object
required:
- status
- data
properties:
status:
const: fail
data:
type: object
required:
- error_message
properties:
error_message:
type: string
Amount:
type: string
pattern: ^-?[0-9]+\.[0-9]{8}$
description: An exact decimal amount of coins with 8 decimals. Signed amounts may start with '-'. Parse as an integer of the smallest unit, not a float.
examples:
- '0.00024300'
LatestBlocks:
type: object
required:
- blocks
properties:
blocks:
type: array
maxItems: 10
description: The ten newest blocks, newest first.
items:
$ref: '#/components/schemas/LatestBlock'
parameters:
hash_or_height:
name: hash_or_height
in: path
required: true
description: A block height (up to 8 digits) or block hash (64 hex characters, any case).
schema:
type: string
pattern: ^([0-9]{1,8}|[0-9a-fA-F]{64})$
example: '769784'
currency:
name: currency
in: query
required: false
description: 'Prices in this currency instead of US dollars (any case). Not a filter: on the paged endpoints it keeps the form you''d get without it.'
schema:
type: string
enum:
- AUD
- BRL
- CAD
- CHF
- CNY
- CZK
- DKK
- EUR
- GBP
- HKD
- HUF
- IDR
- ILS
- INR
- ISK
- JPY
- KRW
- MXN
- MYR
- NOK
- NZD
- PHP
- PLN
- RON
- SEK
- SGD
- THB
- TRY
- USD
- ZAR
network:
name: network
in: path
required: true
description: Network code (any case).
schema:
enum:
- BTC
- LTC
- DOGE
- ZEC
- BTCTEST
- LTCTEST
- DOGETEST
- ZECTEST
example: BTC
securitySchemes:
ApiKey:
type: apiKey
in: header
name: API-KEY
description: Your key, from the dashboard.
ApiKeyQuery:
type: apiKey
in: query
name: api_key
description: Your key as a URL parameter, for lookups (GET) from tools that can't send a header, such as spreadsheets. Best a read-only key.
x-refined-from:
- sochain-com-openapi.json
- dev-sochain-com-openapi.json
- sochain-com-openapi.json