API Reference

Webcash protocol endpoint documentation. This is the protocol API used by webcash.org and implemented by the weby.cash testnet.

Base URLs

Production: https://webcash.org
Testnet: https://weby.cash/api/webcash/testnet

The testnet implements the same protocol as production webcash.org. All endpoints behave identically.

Authentication

The webcash protocol is permissionless. No API keys, no accounts, no authentication. Bearer secrets (the full e…:secret:… string) serve as both identity and authorization. Anyone who knows the secret can spend that webcash.

Endpoints

GET /api/v1/target

Current mining difficulty target. Returns the number of leading zero bits required for a valid proof-of-work.

Response

{
  "difficulty_target": 28,
  "epoch": 42,
  "mining_amount": "200.0",
  "mining_subsidy_amount": "200.0",
  "ratio": 1.0
}
POST /api/v1/mining_report

Submit a mining proof-of-work. The preimage must hash to a value with the required number of leading zero bits. On success, the claimed secret webcash output is created.

Request body

{
  "preimage": "sha256_preimage_hex...",
  "legalese": {
    "terms": true
  }
}

Response

{
  "status": "ok",
  "amount": "200.0"
}
POST /api/v1/replace

Replace (split/merge) secret webcash strings. The fundamental transfer operation. Inputs are consumed, new secret outputs are created. Total input amount must equal total output amount.

Request body

{
  "webcashes": ["e10:secret:abc123..."],
  "new_webcashes": [
    "e7:secret:def456...",
    "e3:secret:ghi789..."
  ],
  "legalese": {
    "terms": true
  }
}

Response

{
  "status": "ok"
}
POST /api/v1/health_check

Server health and readiness check.

Response

{
  "status": "ok",
  "difficulty_target": 28,
  "epoch": 42
}
POST /api/v1/burn

Permanently destroy a secret webcash string. Removes it from circulation. Irreversible.

Request body

{
  "webcash": "e10:secret:abc123..."
}

Response

{
  "status": "ok",
  "amount": "10.0"
}
GET /api/v1/stats

Public server statistics. Total supply, circulation, mining epoch, and historical data.

Response

{
  "total_mined": "1000000.0",
  "total_burned": "500.0",
  "circulation": "999500.0",
  "epoch": 42,
  "difficulty_target": 28,
  "total_replace_count": 85432
}
SDK Documentation Back to Developers