Documentation for the OCEAN mining pool public API.
Base URL: https://api.ocean.xyz/v1
Example: https://api.ocean.xyz/v1/user_hashrate/3QomtEj5nfzEkxPXoVD3hvxgJDzA6M6evt
Note on hashrate units: Raw hashrate values are returned in hashes/sec. Divide by
2^40(1,099,511,627,776) to convert to TH/s.Estimated hashrate fields are calculated as
(shares * 2^32) / seconds.
Server health check
| Arguments | None |
| Returns | "PONG" |
Latest TIDES snapshot for a user or specific worker
| Arguments | username — Bitcoin address or username. Append .workername to get worker-level data. |
Returns:
| Field | Description |
|---|---|
snap_type |
user or worker |
snap_ts |
Unix timestamp of the snapshot |
shares_60s |
Difficulty1 shares submitted in the 60s window ending at snap_ts |
shares_300s |
Difficulty1 shares submitted in the 300s window ending at snap_ts |
hashrate_60s |
Estimated 60s hashrate in hashes/sec — (shares_60s * 2^32) / 60 |
hashrate_300s |
Estimated 300s hashrate in hashes/sec — (shares_300s * 2^32) / 300 |
lastest_share_ts |
Unix timestamp of the most recently accepted share (up to snap_ts) |
shares_in_tides |
Difficulty1 shares currently inside the TIDES reward window |
estimated_earn_next_block |
Estimated earnings (satoshis) if the pool finds a block at snap_ts |
estimated_bonus_earn_next_block |
Deprecated — always 0 |
estimated_total_earn_next_block |
Equal to estimated_earn_next_block |
estimated_payout_next_block |
estimated_earn_next_block + unpaid |
unpaid |
Earnings not yet paid out (subject to payout policies), in satoshis |
Latest hashrate data for a user across all time windows
| Arguments | username — Bitcoin address or username |
Returns:
| Field | Description |
|---|---|
snap_ts |
Unix timestamp used for 60s and 300s metrics |
db_ts |
Unix timestamp used for 600s and longer metrics |
hashrate_60s |
Estimated 60s hashrate (hashes/sec) |
hashrate_300s |
Estimated 300s hashrate (hashes/sec) |
hashrate_600s |
Estimated 600s hashrate (hashes/sec) |
hashrate_3600 |
Estimated 1hr hashrate (hashes/sec) |
hashrate_86400 |
Estimated 24hr hashrate (hashes/sec) |
Latest hashrate data for all of a user's workers
| Arguments | username — Bitcoin address or username |
| Returns | Same fields as user_hashrate, returned as an array under workers (one entry per worker name), plus user_hashrate for the full user total |
TIDES snapshot for all active workers of a user
| Arguments | username — Bitcoin address or username |
| Returns | Array of statsnap objects — one per currently active worker. See statsnap for field definitions. |
Pool-wide TIDES statistics
| Arguments | None |
Returns:
| Field | Description |
|---|---|
snap_ts |
Unix timestamp of the snapshot |
active_users |
Number of unique users currently active on the pool |
active_workers |
Number of unique workers currently active on the pool |
network_difficulty |
Current Bitcoin network mining difficulty |
current_tides_shares |
Pool-wide difficulty1 shares in the TIDES reward window (normally equals max_tides_shares) |
max_tides_shares |
TIDES window size — network_difficulty * 8 |
current_estimated_block_reward |
Estimated total block reward (satoshis) for the OCEAN default template if a block were found now |
Pool-wide hashrate
| Arguments | None |
Returns:
| Field | Description |
|---|---|
snap_ts |
Unix timestamp of the snapshot |
pool_60s |
Average pool hashrate (hashes/sec) from snap_ts-60 to snap_ts |
pool_300s |
Average pool hashrate (hashes/sec) from snap_ts-300 to snap_ts |
Share log breakdown by block template type
| Arguments | None |
| Returns | Array of difficulty1 shares in the reward window, indexed by template type |
Template index map:
| Index | Template |
|---|---|
0 |
OCEAN Default Template |
1 |
DATUM |
2 |
Bitcoin Core |
3 |
Bitcoin Core w/ Ordisrespector |
4 |
Data-Free |
Blocks found by OCEAN
| Arguments | page (optional), page_size (optional), include_legacy — 0 or 1 to include pre-2018 Eligius blocks |
Returns array of blocks, each with:
| Field | Description |
|---|---|
block_hash |
Bitcoin block hash |
ts |
ISO 8601 timestamp of when the block was found |
legacy |
true if from Eligius (pre-2018), false if OCEAN |
username |
Username of the miner who found the block |
workername |
Worker name of the miner who found the block |
solution |
Block header |
network_difficulty |
Bitcoin network difficulty at the time of the block |
height |
Block height |
generation_txn_hash |
Transaction ID of the coinbase (generation) transaction |
accepted_shares |
Difficulty1 shares submitted since the previous block |
subsidy_sats |
Block subsidy portion of the reward, in satoshis |
txn_fees_sats |
Transaction fee portion of the reward, in satoshis |
total_reward_sats |
Total block reward, in satoshis |
sharelog_window |
Difficulty1 shares rewarded by TIDES for this block |
Most recent block found by OCEAN
Alias for blocks/0/1/0. Returns a single-element array. See blocks for field definitions.
Earnings and payouts for a date range
| Arguments | username — Bitcoin address or username. Timestamps can be YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, or a Unix timestamp. Defaults to past 30 days if omitted. |
Returns:
earnings array — one entry per OCEAN block:
| Field | Description |
|---|---|
block_hash |
Block hash of the OCEAN block |
ts |
Block timestamp |
shares_in_window |
Difficulty1 shares rewarded for this user (see TIDES docs) |
fees_collected_satoshis |
Pool fee collected for this block and user, in satoshis |
satoshis_net_earned |
Miner earnings after pool fee, in satoshis |
payouts array — one entry per payout transaction:
| Field | Description |
|---|---|
ts |
Timestamp of the payout transaction |
on_chain_txid |
Bitcoin transaction ID of the payout |
total_satoshis_net_paid |
Amount paid to this user in this transaction, in satoshis |
is_generation_txn |
true if paid directly from the coinbase transaction |
Payout transactions for a given month
| Arguments | username, optional YYYY-MM (defaults to current month), optional format: json (default), text, or csv |
Specifying
csvtriggers a file download in most browsers.
Returns:
| Field | Description |
|---|---|
TimeUTC |
ISO 8601 formatted date/time |
PayoutAmt |
Payout amount, in satoshis |
PayoutAddress |
Bitcoin address paid (the username) |
TXID |
Bitcoin transaction ID |
Generated |
true if paid from the block's coinbase input; false otherwise |
Per-block earnings for a given month
| Arguments | username, optional YYYY-MM (defaults to current month), optional format: json (default), text, or csv |
To convert hash values to difficulty1 shares, divide by
2^32.
Returns:
| Field | Description |
|---|---|
TimeUTC |
ISO 8601 formatted date/time |
Blockheight |
Bitcoin block height of the OCEAN block |
GrossUserRwd |
Total BTC rewarded before pool fees, in satoshis |
GrossUserXctnRwd |
Portion of GrossUserRwd from transaction fees |
NetUserRwd |
GrossUserRwd minus pool fees, in satoshis |
UserHashSinceLastRwd |
Approximate hashes by this user since the last reward |
PoolHashSinceLastRwd |
Approximate hashes by the entire pool since the last reward |
UserHashesInShareLog |
Approximate user hashes inside the share log window for these earnings |
PoolHashesInShareLog |
Approximate pool-wide hashes in the share log window at this block |
Daily hashrate and earnings summary for a given month
| Arguments | username, optional YYYY-MM (defaults to current month), optional format: json (default), text, or csv |
Returns:
| Field | Description |
|---|---|
date |
YYYY-MM-DD |
username |
The username, echoed per row (text/csv only) |
hashrate_avg_24hr_thsec |
Average hashrate for the day in TH/s |
earnings_btc |
Earnings from blocks for that day, in BTC |
- All monetary values are in satoshis (1 BTC = 100,000,000 satoshis) unless otherwise noted.
monthly_user_reportreturns hashrate already converted to TH/s. All other raw hashrate fields are in hashes/sec — divide by2^40to convert.- TIDES (Time-Decaying Eligible Shares) is OCEAN's reward mechanism. See OCEAN's TIDES documentation for details.