1. How confirmation works
- A worker opens a task. The exchange creates a dispatch and pushes it to your platform webhook (or it waits in your poll feed).
- Your platform verifies the real action happened on your side.
- Your server calls
POST /platform/tasks/{uuid}/confirm with a signed request.
- The exchange validates the HMAC, timestamp, nonce and idempotency key, then releases the reward into the verification hold.
Anti-cheat guarantee.
A worker cannot release credits by clicking anything. Only your signed server callback (or an administrator approving a manual submission) can credit the account.
2. Onboarding
Ask an administrator to create a platform in Admin → Platforms, or self-register with the provisioning key:
POST https://lntshar.mihosting.site/api/v1/platforms/register
X-Provision-Key: <platform_provision_key>
Content-Type: application/json
{
"name": "MySocialApp",
"contact_email": "ops@platform.example",
"webhook_url": "https://platform.example/webhooks/exchange",
"callback_url": "https://platform.example/callbacks/exchange",
"networks": ["instagram", "tiktok"]
}
The response contains credentials.api_key (pk_live_…) and credentials.api_secret. The secret is shown once. Store it in your secret manager.
3. Request signing
Every platform request carries these headers:
| Header | Purpose |
Authorization | Bearer pk_live_… API key |
X-Timestamp | Unix seconds; must be within ±300s |
X-Nonce | Random 8–128 char string, single use |
X-Signature | Lowercase hex HMAC-SHA256 |
Idempotency-Key | Optional stable key for safe retries |
The signature is computed over this exact string:
timestamp + "\n" + nonce + "\n" + METHOD + "\n" + path + "\n" + raw_body
path is the signed URL path, e.g. /api/v1/platform/tasks/<uuid>/confirm.
<?php
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(16));
$body = json_encode(['status' => 'confirmed', 'evidence' => 'like-123']);
$path = '/api/v1/platform/tasks/' . $uuid . '/confirm';
$payload = $timestamp . "\n" . $nonce . "\n" . 'POST' . "\n" . $path . "\n" . $body;
$signature = hash_hmac('sha256', $payload, $apiSecret);
// Send with curl/fetch using the headers above.
A nonce is burned after the first successful signature check. Replaying the same nonce returns 409 replay_detected.
4. Platform endpoints
| Method | Path | Description |
| GET | /platform/tasks | Poll open dispatches (?status=) |
| GET | /platform/tasks/{uuid} | Fetch one dispatch |
| POST | /platform/tasks/{uuid}/ack | Acknowledge receipt |
| POST | /platform/tasks/{uuid}/confirm | Signed confirmation — releases the reward |
| POST | /platform/tasks/{uuid}/reject | Signed rejection |
Confirmation body:
{
"status": "confirmed",
"evidence": "optional platform-side id or proof",
"completed_at": "2026-01-01T12:00:00Z"
}
Success response:
{
"ok": true,
"idempotent": false,
"status": "completed",
"completion_id": 42,
"settled": false,
"task": { "task_uuid": "…", "status": "pending_verification", "reward": 12 }
}
5. Worker endpoints (browser session)
These are used by the built-in earn queue. They require the logged-in session cookie plus X-CSRF-Token on writes.
| Method | Path | Description |
| GET | /earn/sites/next | 8-slot task feed (?network=&order=&type_id=) |
| POST | /earn/sites/{id}/dispatch | Create/open a dispatch |
| POST | /earn/sites/{id}/verify | Check one dispatch |
| POST | /earn/verify/status | Batch status poll |
| POST | /earn/sites/{id}/skip | Skip a task |
| POST | /earn/sites/{id}/report | Report a task |
| POST | /earn/sites/{id}/watch/start | Server-authoritative watch timer |
| POST | /earn/sites/{id}/manual-submit | Self-report for manual review (never auto-credits) |
| POST | /earn/streak/claim | Claim the daily streak bonus |
6. Errors & idempotency
Errors use a stable shape:
{ "ok": false, "error": { "code": "invalid_signature", "message": "Invalid request signature." } }
| Code | HTTP | Meaning |
missing_api_key | 401 | No bearer token |
invalid_api_key | 401 | Unknown or disabled platform |
missing_signature | 401 | Timestamp/nonce/signature missing |
timestamp_out_of_window | 401 | Clock skew over 5 minutes |
invalid_signature | 401 | HMAC mismatch |
replay_detected | 409 | Nonce already used |
dispatch_closed | 409 | Task already completed/rejected |
queue_full | 429 | Worker has 8 open tasks |
Confirmations are idempotent. Retry with the same Idempotency-Key and the server returns the original result with idempotent: true instead of crediting twice.
7. Balances, counters and the other APIs
Every confirmed action writes exactly one completions row and one task ledger entry. Per-platform action counts come from completions joined to campaigns.network; per-platform credits come from credit_transactions joined through the campaign reference.
- Balance flow: how a dispatch, confirmation, escrow and settlement move money, plus ready-made SQL for per-network counters —
docs/API_BALANCE_FLOW.md.
- Platform setup: step-by-step Facebook SDK, YouTube Data API, Telegram bot, X, Spotify, Reddit and website pixel —
docs/PLATFORM_SETUP.md.
- Auto-hits surf: website views, escrow, single-use tokens and the human check —
docs/AUTO_HITS.md.
- Payments: InstaPay, phone wallets, crypto and the signed webhook —
docs/PAYMENTS.md.
The bundled cron/audit-balances.php verifies the invariants (balance = ledger sum, no double confirmation, escrow never negative) and exits non-zero on failure, so it can be wired into monitoring.
تحتاج منصة اختبار؟
أنشئ واحدة من الإدارة ← المنصات، ثم شغّل عامل العرض التجريبي المرفق لتجربة التدفق الموقّع كاملًا من البداية للنهاية.