API Documentation

The POWPAD API lets you deploy and manage proof-of-work blockchains programmatically. Generate addresses, send transactions, track deposits, and receive webhooks - all with simple REST calls.

Base URL

https://privacy.energy/v1

Authentication

All authenticated endpoints require an API key. Include it in the X-API-Key header or as an api_key query parameter.

# Using header (recommended)
curl https://privacy.energy/v1/chains/xxx/balance \
  -H "X-API-Key: pow_your_api_key_here"

# Using query parameter
curl https://privacy.energy/v1/chains/xxx/balance?api_key=pow_your_api_key_here

Rate Limits

Rate limits depend on your pricing tier. Limits reset every hour.

Tier	Requests/Hour	Chains	Wallet API	Webhooks	Price
Free	100	0 (read-only)	No	1	$0
Developer	1,000	2	Yes	10	$79/mo
Startup	10,000	10	Yes	50	$249/mo
Enterprise	100,000	Unlimited	Yes	Unlimited	$999/mo

Free Tier Limitations

Free tier can only access public endpoints (chain stats, address validation). Wallet operations (balance, transfers, deposit addresses) require a paid plan. Upgrade in the dashboard.

List Chains

GET /v1/chains

Returns a list of all live POWPAD chains.

Response

{
  "chains": [
    {
      "name": "X Chain",
      "ticker": "XXX",
      "color": "#00ff88",
      "launchedAt": 1705942800000
    }
  ]
}

Get Chain Stats

GET /v1/chains/:ticker/stats

Get network and pool statistics for a chain.

Response

{
  "chain": { "name": "X Chain", "ticker": "XXX" },
  "network": {
    "height": 12847,
    "difficulty": 1203,
    "hashrate": 20,
    "synchronized": true
  },
  "pool": {
    "miners": 5,
    "hashrate": 4200,
    "blocksFound": 847,
    "fee": 1
  }
}

Validate Address

GET /v1/chains/:ticker/validate/:address

Check if an address is valid for this chain.

Response

{
  "valid": true,
  "integrated": false,
  "nettype": "mainnet"
}

Create Deposit Address

POST /v1/chains/:ticker/addresses Auth Required

Generate a new deposit address. The address will be monitored for incoming transactions and trigger webhooks.

Request Body

Parameter	Type	Description
`label`	string	Optional label for the address

Response

{
  "address": "9mV37g7iQtUCgkCfBqhGGg2xv1NduzTEPjgePggNsGeT...",
  "addressIndex": 1
}

Get Balance

GET /v1/chains/:ticker/balance/:address Auth Required

Get the balance of a specific address.

Response

{
  "address": "9mV37g7iQtUCgkCfBqhGGg2xv1NduzTEPjgePggNsGeT...",
  "balance": 50000000000000,
  "balanceFormatted": "50.00000000",
  "unlockedBalance": 45000000000000,
  "unlockedFormatted": "45.00000000",
  "blocksToUnlock": 12
}

Send Transfer

POST /v1/chains/:ticker/transfer Auth Required

Send coins to an address.

Request Body

Parameter	Type	Description
`address` required	string	Destination address
`amount` required	number	Amount to send (in coins, not atomic units)
`paymentId`	string	Optional 64-character hex payment ID

Response

{
  "txid": "a1b2c3d4e5f6...",
  "txKey": "f6e5d4c3b2a1...",
  "fee": 10000000,
  "feeFormatted": "0.00001000"
}

Transaction History

GET /v1/chains/:ticker/transactions Auth Required

Get transaction history for the wallet.

Query Parameters

Parameter	Type	Description
`type`	string	`in`, `out`, or omit for both
`limit`	number	Max results (default 50, max 100)

Response

{
  "transactions": [
    {
      "txid": "a1b2c3d4...",
      "direction": "in",
      "amount": 50000000000000,
      "amountFormatted": "50.00000000",
      "height": 12345,
      "timestamp": 1705942800,
      "confirmations": 60,
      "locked": false
    }
  ]
}

Create Webhook

POST /v1/chains/:ticker/webhooks Auth Required

Request Body

Parameter	Type	Description
`url` required	string	HTTPS URL to receive webhook POSTs
`events` required	array	Events to subscribe to

Response

{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhook",
  "events": ["deposit.received"],
  "secret": "whsec_..."
}

Save Your Secret

The webhook secret is only shown once. Use it to verify webhook signatures.

Webhook Events

Webhooks are sent as POST requests with a JSON body. Verify the signature using the X-POWPAD-Signature header.

Event	Description
`deposit.received`	New deposit detected on a tracked address
`block.found`	New block mined on the network
`transfer.sent`	Outgoing transfer completed
`*`	Subscribe to all events

Webhook Payload

{
  "event": "deposit.received",
  "timestamp": 1705942800000,
  "data": {
    "address": "9mV37g7iQtUCgkCfBqhGGg2xv1NduzTEPjgePggNsGeT...",
    "amount": 50000000000000,
    "amountFormatted": "50.00000000",
    "txid": "a1b2c3d4...",
    "confirmations": 1
  }
}

Verifying Signatures

// Node.js example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === expected;
}