Simulator
Support
App
Addresses
🚀Get started 🚀

API Reference
Getting Started
Overview
HMAC Authentication
Endpoints
Profile
Workers
Payments
Assets
Legacy Addresses
Referrals
Dashboard
Addresses
Withdraw Settings
Meta
Simulator
Overview

The API provides programmatic access to unMineable platform features using HMAC-SHA256 signature authentication. This stateless API is designed for server-to-server integrations and power users.

Base URL
https://api.unmineable.dev/v1
Authentication
Public metadata and simulator routes do not require signing. All other requests must be signed with HMAC-SHA256 using your API credentials.
Rate Limits
500 requests per minute per token/IP
HMAC Authentication

Authenticated endpoints require three HTTP headers:

x-user-api-key
Your API token public key
x-user-api-timestamp
13-digit Unix timestamp in milliseconds
x-user-api-signature
Lowercase hex HMAC-SHA256 signature

Signature Payload

The signature is computed by concatenating the following values with newline characters:

<HTTP_METHOD>
<request path>
<raw query string (without ?)>
<x-user-api-timestamp>
<sha256 hex of raw request body>

Scope Rules

read
GET and HEAD requests only
read_write
GET, POST, PATCH, and DELETE requests

Error Codes

401 UNAUTHORIZED
Invalid or missing credentials
401 INVALID_SIGNATURE
HMAC signature verification failed
401 INVALID_TIMESTAMP
Request timestamp outside 5-minute window
403 INSUFFICIENT_SCOPE
Token lacks required scope for this operation
403 IP_NOT_ALLOWED
Request IP not in token's allowed IPs list
409 USER_ALIAS_REQUIRED
User must create a default alias first

Code Example (JavaScript)

const crypto = require('crypto');

function signRequest(method, path, queryString, body, timestamp, secret) {
  const payload = [
    method.toUpperCase(),
    path,
    queryString || '',
    timestamp,
    crypto.createHash('sha256').update(body || '').digest('hex')
  ].join('\n');
  return crypto.createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
}

const timestamp = Date.now().toString();
const signature = signRequest('GET', '/v1/me', '', '', timestamp, 'your-secret');
Profile
GET
/v1/me
Retrieves the current account's profile information including UUID, email, username, referral code, and alias status.
Auth: required (scope: read)
Headers
x-user-api-key: upk_abc123...
x-user-api-timestamp: 1743460800000
x-user-api-signature: a1b2c3d4...
POST
/v1/me
Updates exactly one profile field per request. Accepts username (to create the default alias) or referrer_code, including null to clear it.
Auth: required (scope: read_write)
REQUEST (Username)
{ "username": "myalias" }
Workers
GET
/v1/workers
Lists all workers with pagination, filters, and sorting. Returns unfiltered counts and filtered breakdown counters.
Auth: required (scope: read, alias required)
Query params:
page, algorithm, online, region, name, chart_algo, period, sort, dir
Query String
?page=1&algorithm=randomx&online=true&chart_algo=randomx&period=24h&sort=last_seen&dir=desc
GET
/v1/workers/counts
Returns worker counts: total, online, and offline.
Auth: required (scope: read, alias required)
Query String
GET
/v1/workers/chart
Returns timeseries hashrate data grouped by algorithm for charting.
Auth: required (scope: read, alias required)
Query params:
chart_algo, period (1h|24h)
Query String
?period=24h&chart_algo=randomx
Payments
GET
/v1/payments
Paginated user payments with coin/network enrichment and filtered counters.
Auth: required (scope: read, alias required)
Query params:
page, coin, network, date_from, date_to, tz, status, sort, dir
Query String
?page=1&coin=BTC&network=BTC&date_from=2026-03-01&date_to=2026-03-31&tz=-180&status=success&sort=timestamp&dir=desc
POST
/v1/payments
Requests a manual payout. The payout amount is derived from the account's balance.
Auth: required (scope: read_write, alias required)
REQUEST
{ "coin": "BTC", "uuid": "addr-uuid" }
GET
/v1/payments/:uuid/events
Returns the timeline of events for a specific payment.
Auth: required (scope: read, alias required)
Path
/v1/payments/550e8400-e29b-41d4-a716-446655440001/events
Assets
GET
/v1/assets
Returns the account's mixed asset catalog including coin assets and attached legacy addresses.
Auth: required (scope: read, alias required)
Query params:
is_active, sort, dir
Query String
?is_active=true&sort=amount&dir=desc
GET
/v1/assets/:coin/stats
Returns coin-level stats including balance, mining rewards, referral rewards, and payment totals.
Auth: required (scope: read, alias required)
Path
/v1/assets/BTC/stats
POST
/v1/assets/update
Replaces the current reward distribution for the signed-in account. Accepts { coins: [...] }, { targets: [...] }, or a bare array.
Auth: required (scope: read_write, alias required)
REQUEST
{
  "targets": [
    { "type": "coin", "coin": "BTC", "reward_hashrate_percentage": 0.6, "reward_algorithm": "randomx" },
    { "type": "legacy_address", "uuid": "legacy-address-uuid", "reward_hashrate_percentage": 0.4 }
  ]
}
Legacy Addresses
POST
/v1/legacy-addresses/attach
Attaches an existing shared legacy address to the signed-in account.
Auth: required (scope: read_write, alias required)
REQUEST
{ "uuid": "legacy-address-uuid" }
GET
/v1/legacy-addresses/:uuid
Returns the current settings for one attached legacy address.
Auth: required (scope: read, alias required)
Path
/v1/legacy-addresses/550e8400-e29b-41d4-a716-446655440002
GET
/v1/legacy-addresses/:uuid/stats
Returns shared legacy-address stats including balance and reward totals.
Auth: required (scope: read, alias required)
Path
/v1/legacy-addresses/550e8400-e29b-41d4-a716-446655440002/stats
PATCH
/v1/legacy-addresses/:uuid
Updates settings for an attached legacy address.
Auth: required (scope: read_write, alias required)
REQUEST
{ "auto_detach_on_payment": true }
DELETE
/v1/legacy-addresses/:uuid
Detaches a legacy address from the signed-in account.
Auth: required (scope: read_write, alias required)
Path
/v1/legacy-addresses/550e8400-e29b-41d4-a716-446655440002
POST
/v1/legacy-addresses/:uuid/payments
Requests a manual payout for an attached legacy address.
Auth: required (scope: read_write, alias required)
REQUEST
{ "platform": "api" }
Referrals
GET
/v1/referrals
Lists referred workers for the signed-in account across account-flow and legacy sources.
Auth: required (scope: read)
Query params:
page, type, algorithm, online, sort, dir
Query String
?page=1&type=user,legacy&online=true
Dashboard
GET
/v1/dashboard/assets
Minimal assets view for quick dashboard rendering.
Auth: required (scope: read, alias required)
Path
/v1/dashboard/assets
GET
/v1/dashboard/summary
Latest summarized snapshot of dashboard data.
Auth: required (scope: read, alias required)
Path
/v1/dashboard/summary
GET
/v1/dashboard/events
Paginated dashboard events including worker, reward, and payout events.
Auth: required (scope: read, alias required)
Query params:
page, type, dir
Query String
?page=1&type=worker,reward,payout&dir=desc
Addresses
GET
/v1/addresses
Lists all withdraw addresses owned by the current account.
Auth: required (scope: read, alias required)
Query params:
network, enabled, page, sort, dir
Query String
?network=BTC,ETH&enabled=1&page=1
POST
/v1/addresses
Creates a new withdraw address.
Auth: required (scope: read_write, alias required)
REQUEST
{
  "network": "ETH",
  "alias": "Main Wallet",
  "address": "0xabc123...",
  "memo": "",
  "platform": "api"
}
PATCH
/v1/addresses/:uuid
Updates mutable fields for an existing withdraw address.
Auth: required (scope: read_write, alias required)
Query params:
dry_run
REQUEST
{ "alias": "New Label", "platform": "api" }
DELETE
/v1/addresses/:uuid
Soft-deletes a withdraw address.
Auth: required (scope: read_write, alias required)
Query params:
dry_run
Path
/v1/addresses/550e8400-e29b-41d4-a716-446655440098
Withdraw Settings
GET
/v1/assets/:coin/withdraw/address
Returns the current withdrawal preference for a specific asset.
Auth: required (scope: read, alias required)
Path
/v1/assets/BTC/withdraw/address
POST
/v1/assets/:coin/withdraw/address
Sets withdrawal preferences for a specific asset.
Auth: required (scope: read_write, alias required)
REQUEST
{
  "uuid": "addr-uuid",
  "payment_threshold": "0.005",
  "auto_withdraw": true
}
Meta
GET
/v1/meta/coin
Public coin metadata with optional compact mode and categories grouping.
Auth: none
Query params:
compact, categories
Query String
?compact=true
GET
/v1/meta/coin/:coin
Public coin detail for a specific coin.
Auth: none
Path
/v1/meta/coin/ADA
Simulator
POST
/v1/simulator
Public forward mining simulator for advanced and device modes.
Auth: none
REQUEST
{
  "mode": "advanced",
  "coin": "BTC",
  "algorithm": "randomx",
  "hashrate_hs": "120000000",
  "scenario_set": "default",
  "referral_discount": false
}
Back to top