API Reference

Complete reference for the TxProof API methods.
Base URL: https://api.txproof.xyz

Live v1

Multi-Chain Ready

Infrastructure

GET/api/v1/chains

Returns a dynamic list of blockchain networks supported by the platform. Use this to populate network selectors in your UI.

{
  "success": true,
  "chains": [
    {
      "id": 1,
      "name": "Ethereum",
      "symbol": "ETH",
      "icon": "🔷",
      "explorer": "etherscan.io"
    },
    {
      "id": 8453,
      "name": "Base",
      "symbol": "ETH",
      "icon": "🔵",
      "explorer": "basescan.org"
    },
    {
      "id": 137,
      "name": "Polygon",
      "symbol": "POL",
      "icon": "🟣",
      "explorer": "polygonscan.com"
    }
  ]
}

Receipt Generation

POST/api/v1/bills/resolve

Starts a background job to generate a receipt for a specific blockchain transaction. This is an idempotent operation.

Request Body

txHash *

string

The transaction hash (0x...).

chainId *

number

The EVM chain ID (e.g. 1, 137, 8453).

Example

curl -X POST https://api.txproof.xyz/api/v1/bills/resolve \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "txHash": "0x5d962...", "chainId": 1 }'

GET/api/v1/bills/job/:jobId

Poll status of a generation job.

{
  "id": "job_123",
  "state": "completed",
  "data": "https://storage.txproof.xyz/receipts/bill-1-0x123.json",
  "pdfUrl": "https://storage.txproof.xyz/..."
}

Webhooks

POST/api/v1/webhooks

{
  "url": "https://your-api.com/webhooks/txproof",
  "events": ["bill.created", "bill.failed"]
}

GET/api/v1/webhooks

List all active webhooks.

DELETE/api/v1/webhooks/:id

Delete a webhook subscription.

POST/api/v1/webhooks/:id/rotate

Rotates the signing secret for a webhook. This invalidates the old secret immediately.
Note: Returns the new secret only once.

{
  "webhook": { 
    "id": "wh_123", 
    "url": "https://...", 
    "health_status": "active" 
  },
  "secret": "whsec_..." 
}

Webhook Payloads

When an event occurs, TxProof sends a POST request to your URL with a JSON payload. Events now include dynamic chain metadata for easier processing.

{
  "id": "job_123",
  "bill_id": "bill_abc",
  "status": "completed",
  "tx_hash": "0x...",
  "chain_id": 8453,
  "chain_name": "Base",
  "chain_symbol": "ETH",
  "chain_icon": "🔵",
  "billDataUrl": "https://storage.txproof.xyz/...",
  "duration_ms": 4500
}

Custom Templates

GET/api/v1/templates

Retrieve your current branding configuration.

POST/api/v1/templates

Upload logo and set brand colors for your receipts.

{
  "logo_url": "https://example.com/logo.png",
  "primary_color": "#FF5733",
  "footer_text": "Thank you for your business!"
}

Receipt Verification

POST/api/v1/verify/receipt

Cryptographically verify a receipt's integrity against its stored hash in the database.

Example Request

curl -X POST https://api.txproof.xyz/api/v1/verify/receipt \
  -H "Content-Type: application/json" \
  -d '{ "billId": "550e8400-e29b-41d4-a716-446655440000" }'

Response

{
  "valid": true,
  "billId": "550e8400-e29b-41d4-a716-446655440000",
  "algorithm": "keccak256",
  "storedHash": "0xabc123...",
  "computedHash": "0xabc123...",
  "verified_at": "2024-03-20T10:00:00Z"
}

Usage & Quotas

GET/api/v1/usage

Get real-time usage metrics for the authenticated API key.

{
  "plan": {
    "name": "Professional",
    "limit": 50000,
    "rateLimitRps": 50
  },
  "usage": {
    "total": 12450,
    "remaining": 37550,
    "period": { "start": "2024-03-01...", "end": "..." }
  }
}

Account & Keys

GET/api/v1/me

Get authenticated user profile and quota details.

GET/api/v1/keys

List all active API keys.

POST/api/v1/keys

Create a new API key.

POST/api/v1/keys/:id/revoke

Revoke an existing API key.