Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Sochain Com Network & price API
version: '3'
description: 'Operations tagged Network & price 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: Network & price
paths:
/network_info/{network}:
get:
operationId: get_network_info
tags:
- Network & price
summary: Network state and mempool
description: Newest block, hashrate, mempool size and the next six projected blocks with their fee rates.
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/NetworkInfo'
example:
status: success
data:
block_count: 969109
best_block_hash: 000000000000000000000474eca618c25628bef0c45f29aaea93af7a28384413
hashrate: '1058892548723656000000'
mempool:
mempool_txs: 47709
mempool_size: 14608422
updated_at: 1790662718
blocks:
- block_num: 1
min_fee_rate: 1
max_fee_rate: 80
median_fee_rate: 1
min_fee_rate_possible: 1
weight: 3974745
size: 1535022
num_txs: 4560
- block_num: 2
min_fee_rate: 1
max_fee_rate: 3
median_fee_rate: 1
min_fee_rate_possible: 1
weight: 3995979
size: 1812555
num_txs: 4398
'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 network info. 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/network_info
servers:
- url: https://sochain.com/api/v3
/price/{network}:
get:
operationId: get_price
tags:
- Network & price
summary: Latest price
description: 'The latest price, in US dollars or the currency asked for. Testnets: always 0.00000000.'
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/PriceData'
example:
status: success
data:
value: '16547.91439787'
currency: USD
'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 price data. 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/price
servers:
- url: https://sochain.com/api/v3
/price/{network}/{unix_timestamp}:
get:
operationId: get_price_at
tags:
- Network & price
summary: Price at a past time
description: 'The price at unix_timestamp: its hour''s opening price, or its UTC day''s where hourly prices don''t reach. A time before price history begins answers 404, naming the first day with a price; a time still to come, 404.'
parameters:
- $ref: '#/components/parameters/network'
- $ref: '#/components/parameters/unix_timestamp'
- $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/PriceData'
example:
status: success
data:
value: '16547.91439787'
currency: USD
'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 price data. 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/price
servers:
- url: https://sochain.com/api/v3
/rich_list/{network}:
get:
operationId: get_rich_list
tags:
- Network & price
summary: The largest holders
description: The top 1,000 addresses by confirmed balance, a page at a time, with each one's share of all coins, transactions, first and last activity, and 24-hour and 7-day change. Follows the newest block.
parameters:
- $ref: '#/components/parameters/network'
- $ref: '#/components/parameters/rich_page'
- $ref: '#/components/parameters/rich_page_size'
security:
- {}
- ApiKey: []
- ApiKeyQuery: []
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
required:
- status
- data
properties:
status:
const: success
data:
$ref: '#/components/schemas/RichList'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Unknown network, or a network without a rich list.
content:
application/json:
schema:
$ref: '#/components/schemas/Fail'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/Unavailable'
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'
parameters:
unix_timestamp:
name: unix_timestamp
in: path
required: true
description: 'Unix seconds (7–10 digits): the price at that time. Anything else means the latest price.'
schema:
type: integer
example: 1672533478
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
rich_page:
name: page
in: query
required: false
description: Page, from 1 to 1,000 ÷ page_size.
schema:
type: integer
minimum: 1
maximum: 40
default: 1
rich_page_size:
name: page_size
in: query
required: false
description: Holders per page.
schema:
type: integer
enum:
- 25
- 50
- 100
default: 100
network:
name: network
in: path
required: true
description: Network code (any case).
schema:
enum:
- BTC
- LTC
- DOGE
- ZEC
- BTCTEST
- LTCTEST
- DOGETEST
- ZECTEST
example: BTC
schemas:
ProjectedBlock:
type: object
required:
- block_num
- min_fee_rate
- max_fee_rate
- median_fee_rate
- min_fee_rate_possible
- weight
- size
- num_txs
description: A block projected from the mempool. Fee rates are per virtual byte, in satoshis (BTC, BTCTEST), litoshis (LTC, LTCTEST) or koinu (DOGE, DOGETEST); on Zcash (ZEC, ZECTEST), zatoshis per logical action (ZIP 317).
properties:
block_num:
type: integer
minimum: 1
maximum: 6
min_fee_rate:
type: integer
max_fee_rate:
type: integer
median_fee_rate:
type: integer
min_fee_rate_possible:
type: integer
min_fee_rate_precise:
type: string
description: min_fee_rate to two decimal places ("0.31"), so rates under one unit show.
median_fee_rate_precise:
type: string
description: median_fee_rate to two decimal places.
max_fee_rate_precise:
type: string
description: max_fee_rate to two decimal places.
min_fee_rate_possible_precise:
type: string
description: min_fee_rate_possible to two decimal places.
weight:
type: integer
size:
type: integer
num_txs:
type: integer
fee_unit:
const: zat/action
description: 'Zcash only: the rates on this block are zatoshis per logical action (ZIP 317), not per byte.'
marginal_fee:
type: integer
description: 'Zcash only: the ZIP 317 fee per logical action, in zat.'
grace_actions:
type: integer
description: 'Zcash only: the fewest actions a fee pays for, 2.'
PriceData:
type: object
required:
- value
- currency
properties:
value:
$ref: '#/components/schemas/Amount'
currency:
type: string
description: USD, or the currency you asked for.
as_of:
type: integer
description: When the latest price was taken (Unix time). On the latest price only.
RichList:
type: object
required:
- height
- time
- supply
- page
- page_size
- total_rows
- rows
properties:
height:
type: integer
description: The newest block the list reflects.
time:
type: integer
supply:
$ref: '#/components/schemas/Amount'
description: 'Every confirmed coin: what share_of_supply divides by.'
page:
type: integer
page_size:
type: integer
total_rows:
type: integer
description: Holders listed, at most 1,000.
rows:
type: array
items:
type: object
properties:
rank:
type: integer
address:
type:
- string
- 'null'
description: null for coins in outputs with no address (pay-to-public-key, bare multisig).
balance:
$ref: '#/components/schemas/Amount'
received:
$ref: '#/components/schemas/Amount'
sent:
$ref: '#/components/schemas/Amount'
share_of_supply:
type:
- number
- 'null'
tx_count:
type: integer
first_seen:
type:
- object
- 'null'
properties:
height:
type: integer
time:
type: integer
description: '{height, time} of that activity.'
last_seen:
type:
- object
- 'null'
properties:
height:
type: integer
time:
type: integer
description: '{height, time} of that activity.'
delta_24h:
type:
- string
- 'null'
description: Balance change over 24 hours, 8 decimals.
delta_7d:
type:
- string
- 'null'
description: Over 7 days.
label:
type: 'null'
description: Reserved.
QuoteTarget:
type: object
properties:
fee_rate:
type: integer
description: The lowest rate, in koinu/vB, at which payments got into a block within within_blocks blocks, as often as confidence says.
within_blocks:
type:
- integer
- 'null'
description: How many blocks the quote is for.
Fail:
type: object
required:
- status
- data
properties:
status:
const: fail
data:
type: object
required:
- error_message
properties:
error_message:
type: string
NetworkInfo:
type: object
required:
- block_count
- best_block_hash
- hashrate
- mempool
properties:
block_count:
type: integer
description: Height of the newest block.
best_block_hash:
type: string
hashrate:
type: string
description: Estimated hashes per second (solutions per second on Zcash), as a decimal string.
mempool:
type: object
required:
- mempool_txs
- mempool_size
- updated_at
- blocks
properties:
mempool_txs:
type: integer
mempool_size:
type: integer
description: Bytes.
updated_at:
type: integer
blocks:
type: array
maxItems: 6
items:
$ref: '#/components/schemas/ProjectedBlock'
loading:
type: boolean
description: 'true while the mempool is still being read in: its counts can be low until this turns false.'
quote_targets:
type:
- object
- 'null'
description: 'Dogecoin only: fee rates its pools have accepted lately, learned from the last samples blocks with payments. fast, normal and slow are each { fee_rate, within_blocks }: the lowest rate (koinu/vB, like the rates beside it) at which payments got into a block within within_blocks blocks, as often as confidence says (0.95: 95% of the time). null on other networks, and until it has learned.'
properties:
fast:
$ref: '#/components/schemas/QuoteTarget'
normal:
$ref: '#/components/schemas/QuoteTarget'
slow:
$ref: '#/components/schemas/QuoteTarget'
confidence:
type: number
description: How often the quotes held, from 0 to 1.
samples:
type: integer
description: Blocks with payments they're learned from.
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'
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