Toolfuz API

Overview

The Toolfuz API is JSON over HTTPS. Authenticate with a Bearer API key in the Authorization header. Use the idempotency header when creating resources to prevent duplicates on retries. Events are delivered via HMAC-signed webhooks.

Contents

1. Endpoints
2. Create invoice
3. Retrieve invoice
4. Plans catalog
5. Service health
6. Webhooks
7. Errors
8. Rate limits & quotas
9. Code examples

Endpoints

• GET /api/health/ — service status JSON
• GET /api/plans/ — plans catalog JSON
• POST /api/invoices/ — create an invoice
• GET /api/invoices/{id} — retrieve an invoice

Create invoice

Create a Litecoin invoice that your customer can pay. We’ll emit webhook events on detection and confirmations.

curl -X POST https://toolfuz.com/api/invoices/ \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f2a2f2a-aaaa-bbbb-cccc-333333333333" \
  -d '{
    "amount": "0.25",
    "currency": "LTC",
    "memo": "Order #12345",
    "callback_url": "https://merchant.site/webhook",
    "ttl_minutes": 30,
    "confirmations_required": 1
  }'

{
  "id": "inv_14186ac844b4",
  "status": "pending",
  "currency": "LTC",
  "amount": "0.25000000",
  "pay_to_address": "ltc1q....",
  "expires_at": "2025-08-24T12:15:44Z",
  "checkout_url": "https://toolfuz.com/checkout?id=inv_14186ac844b4"
}

Retrieve invoice

curl https://toolfuz.com/api/invoices/inv_14186ac844b4 \
  -H "Authorization: Bearer <YOUR_API_KEY>"

{
  "id": "inv_14186ac844b4",
  "status": "settled",
  "received": "0.07508134",
  "confirmations": 3,
  "created_at": "2025-08-24T11:45:44Z",
  "expires_at": "2025-08-24T12:15:44Z"
}

Plans catalog

curl https://toolfuz.com/api/plans/

{
  "currency": "USD",
  "plans": [
    {"id":"starter","name":"Starter","monthly":19},
    {"id":"pro","name":"Pro","monthly":49},
    {"id":"business","name":"Business","monthly":199}
  ]
}

Service health

curl https://toolfuz.com/api/health/

{
  "ok": true,
  "network": "litecoin-mainnet",
  "height": 2800000,
  "node_synced": true
}

Webhooks

Set callback_url when creating an invoice. We sign each delivery with an HMAC SHA-256 signature header so you can verify authenticity.

<?php
$secret = 'YOUR_WEBHOOK_SECRET'; // from dashboard/config
$payload = file_get_contents('php://input');
$hdr = $_SERVER['HTTP_X_TOOLFUZ_SIGNATURE'] ?? '';
// header format: t=timestamp,v1=hex_hmac
parse_str(str_replace([',',' '], ['&',''], $hdr), $parts);
$timestamp = $parts['t'] ?? '';
$sig = $parts['v1'] ?? '';

$base = $timestamp . '.' . $payload;
$calc = hash_hmac('sha256', $base, $secret);
if (!hash_equals($calc, $sig)) {
  http_response_code(400); exit('invalid signature');
}

$event = json_decode($payload, true);
// handle $event['type'] and $event['data']
http_response_code(200); echo 'ok';

Errors

Errors return non-2xx status codes with a JSON body:

{
  "error": {
    "code": "bad_request",
    "message": "amount is required"
  }
}

Rate limits & quotas

• Per-plan monthly quotas; live RPM (requests/min) throttling.
• Headers may include X-RateLimit-Remaining and Retry-After.
• Use Idempotency-Key for safe retries on POST.

Code examples

<?php
$payload = [
  "amount" => "0.25",
  "currency" => "LTC",
  "memo" => "Order #12345",
  "callback_url" => "https://merchant.site/webhook"
];
$ch = curl_init("https://toolfuz.com/api/invoices/");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_API_KEY",
    "Content-Type: application/json",
    "Idempotency-Key: 2f2a2f2a-aaaa-bbbb-cccc-333333333333"
  ],
  CURLOPT_POSTFIELDS => json_encode($payload),
]);
$res = curl_exec($ch);
curl_close($ch);
echo $res;

const payload = {
  amount: "0.25",
  currency: "LTC",
  memo: "Order #12345",
  callback_url: "https://merchant.site/webhook"
};
const r = await fetch("https://toolfuz.com/api/invoices/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": "2f2a2f2a-aaaa-bbbb-cccc-333333333333"
  },
  body: JSON.stringify(payload)
});
console.log(await r.json());