API reference

Authentication

Send your credentials as headers (recommended) or in the JSON body. The demo sandbox keys are shown below.

Silkroute-Client-Id: client_demo_5f3a9c
Silkroute-Secret: sandbox-secret-DEMO-do-not-use

Creates a short-lived token that initialises the Link widget for one end user.

{
  "user_ref": "user_42",
  "products": ["transactions", "payments"],
  "language": "uz"
}

{
  "link_token": "link-sandbox-3f9a…",
  "expiration": "2026-09-29T12:30:00.000Z"
}

Exchanges the one-time public_token returned by Link for a permanent access_token. Revealed exactly once. A public_token is valid for 30 minutes. If you created the link_token with code_challenge (PKCE, method S256), send the matching code_verifier.

{ "public_token": "public-sandbox-…" }

{
  "access_token": "access-sandbox-…",
  "item_id": "item_01H…"
}

Returns real-time balances for every open account on the Item. Amounts are in major units.

{ "access_token": "access-sandbox-…" }

{
  "accounts": [{
    "account_id": "acc_01M…",
    "name": "UZCARD Salary", "mask": "4415",
    "balances": {
      "current": 79802.37, "available": 69160.47,
      "iso_currency_code": "UZS" }
  }]
}

Paginated, enriched transactions. amount is positive when money leaves the account.

{
  "access_token": "…",
  "start_date": "2026-08-01",
  "end_date": "2026-09-29",
  "options": { "count": 100, "offset": 0 }
}

{
  "total_transactions": 78,
  "transactions": [{
    "transaction_id": "txn_…", "amount": 45000,
    "pending": false, "date": "2026-09-20",
    "merchant_name": "Korzinka",
    "personal_finance_category": {
      "primary": "FOOD_AND_DRINK" }
  }]
}

Initiates a direct A2A transfer. Requires an idempotency_key; settlement is confirmed asynchronously. The response carries the simulated platform fee: at most 0.5% (50 bps), 0.3% (30 bps) at monthly volume, capped per payment. Sandbox: nothing is charged.

{
  "access_token": "…",
  "account_id": "acc_…",
  "amount": 150000, "currency": "UZS",
  "creditor": {
    "name": "OOO Beneficiary",
    "account_number": "20208000900123456789" },
  "idempotency_key": "order-4821"
}

{
  "payment_id": "pay_01M…",
  "status": "executing",
  "amount": 150000, "currency": "UZS",
  "fee": { "amount": 750, "currency": "UZS",
           "bps": 50, "tier": "standard", "simulated": true }
}

Account-holder names, e-mail, masked phone and city, fetched from the bank on every call. Silkroute stores none of it. Sandbox identities are synthetic.

{ "access_token": "access-sandbox-…" }

{
  "accounts": [{
    "account_id": "acc_01M…", "mask": "4415",
    "owners": [{
      "names": ["Dilnoza Karimova"],
      "phone_numbers": [{ "data": "+998 ** *** ** 42" }],
      "addresses": [{ "data": { "city": "Samarkand", "country": "UZ" } }]
    }]
  }],
  "data_source": "synthetic_sandbox"
}

Consent centre (Authorization: Bearer user-…): the user’s cash flow per month and spending per category across their connected banks, in whole UZS.

{ "period": "90d" }

{
  "period": { "start": "2026-07-12", "end": "2026-10-09" },
  "cashflow": {
    "totals": { "inflow": 28500000, "outflow": 12900000, "net": 15600000 },
    "savings_rate_pct": 55 },
  "categories": [{ "category": "RENT_AND_UTILITIES",
    "amount": 7900000, "share_pct": 61 }]
}

Consent centre: a read-only assistant. It can only call three fixed tools (cash flow, category spend, risk score) for this user; every figure in the answer is in facts. Without an LLM key the answer is calculated, not generated. Limited per user per day.

{
  "question": "Where did my money go?",
  "language": "en"
}

{
  "answer": "From 2026-07-12 to 2026-10-09 you received 28 500 000 UZS …",
  "mode": "llm",
  "sources": [{ "tool": "get_cashflow", "period": { … } }],
  "facts": [ … ],
  "usage": { "questions_today": 1, "daily_limit": 10 }
}

Create a mandate on the user’s account, wait for the user to approve it (consent centre or Telegram), then charge variable amounts within the limits. Above-limit or inactive-mandate attempts come back with status "rejected" and a rejection_code — HTTP 200, not an error — and are still logged.

{
  "access_token": "access-sandbox-…",
  "account_id": "acc_01J…",
  "payee": { "name": "Shahar Kommunal",
             "account_number": "20208000900765432109" },
  "limits": { "max_per_payment": 500000,
              "period": "month",
              "period_limit": 1000000 },
  "expires_at": "2027-10-01T00:00:00Z"
}

{
  "mandate": {
    "mandate_id": "mandate_01J…",
    "status": "awaiting_authorization",
    "payee": { "name": "Shahar Kommunal",
               "account_mask": "••••2109" },
    "limits": { "max_per_payment": 500000,
                "period": "month", "period_limit": 1000000 },
    "usage": { "used": 0, "remaining": 1000000 }
  }
}

{
  "mandate_id": "mandate_01J…",
  "amount": 645000,
  "idempotency_key": "bill-2026-10-heating"
}

{
  "charge": {
    "charge_id": "vrpc_01J…",
    "status": "rejected",
    "rejection_code": "LIMIT_PER_PAYMENT_EXCEEDED",
    "amount": 645000, "payment_id": null
  },
  "remaining_in_period": 399700
}

Ask the borrower for consent, wait until they grant it, then fetch a 300–850 cash-flow score with five explained factors. The consent_token is returned once and works only while access is granted; every fetch is logged and shown to the borrower.

• Factors: income_stability 0.30 · inflow_regularity 0.15 · spending_ratio 0.20 · balance_resilience 0.15 · debt_burden 0.20. score = 300 + 550 × Σ(weight × sub_score) / 100.
• Flags: HIGH_DEBT_BURDEN (debt service ≥ 50% of income, score capped at 599), INSUFFICIENT_HISTORY (< 3 full months), NO_INCOME_DETECTED.

{
  "user_ref": "borrower_4821",
  "purpose": "Consumer loan application #4821",
  "period_months": 6,
  "access_ttl_days": 30
}

{
  "consent_id": "pcon_01J…",
  "consent_token": "consent-sandbox-…",
  "status": "pending",
  "requester_name": "Acme Microfinance",
  "request_expires_at": "2026-10-10T10:00:00Z"
}

{
  "consent_token": "consent-sandbox-…"
}

{
  "passport": {
    "score": 712, "grade": "B", "confidence": "high",
    "model_version": "cf-v1", "flags": [],
    "factors": [{
      "key": "debt_burden", "weight": 0.2,
      "sub_score": 100, "impact": "positive",
      "explanation": "No loan payments detected."
    }, …],
    "metrics": { "months_observed": 6,
                 "avg_monthly_income": 9500000,
                 "debt_to_income": 0 },
    "data_source": "synthetic_sandbox"
  }
}

Rules belong to the user, so they are created with a user_token from your server (or in the consent centre). The engine projects the protected account from scheduled debits and detected recurring outflows; before a shortfall it suggests a top-up (notify) or transfers immediately (auto). amount = min(shortfall, max_transfer_amount, donor balance above source_min_balance).

• Sandbox: a rule name containing FLAKY makes the first transfer attempt fail once (retry demo); FAIL makes every attempt fail.

{
  "name": "Keep my card topped up",
  "target_account_id": "acc_card…",
  "source_account_id": "acc_savings…",
  "horizon_days": 7,
  "max_transfer_amount": 2000000,
  "source_min_balance": 5000000,
  "mode": "notify"
}

{
  "rule": { "rule_id": "abr_01J…", "status": "active", "mode": "notify" },
  "evaluation": {
    "evaluation": { "action": "transfer", "amount": 900000,
                    "shortfall_date": "2026-10-17",
                    "projected_min_balance": -899877 },
    "execution": { "execution_id": "abx_01J…", "status": "suggested" }
  }
}

{
  "execution_id": "abx_01J…"
}

{
  "execution": {
    "execution_id": "abx_01J…", "status": "executing",
    "amount": 900000, "decided_by": "user",
    "attempts": 1, "max_attempts": 3
  },
  "result": "transfer_confirmed"
}

B2B only: every call acts on behalf of a treasury member of your company — send actor_ref in the body or the Silkroute-Actor header. Roles: director (everything) and accountant (view, preview and initiate payments). The API-key holder can bootstrap the first director; the last active director cannot be demoted or disabled (409 LAST_DIRECTOR). All endpoints are POST under /v1/treasury. A split pays one counterparty from several accounts: each part is a separate A2A bank payment, and the overall status is always derived from the parts.

• Sandbox: sandbox_simulate: { fail_part: <part_no>, failure: "transient" | "permanent", refuse_return: true } on /split/create (sandbox keys only; otherwise SANDBOX_ONLY) lets you watch retries, re-allocation and compensation.
• Execution: each part is a separate A2A payment, retried on a technical bank error (up to 3 attempts per part). If a part fails for good, auto mode re-allocates the missing amount once to other accounts; otherwise already-settled parts are compensated (the counterparty returns them).
• Sub-treasury: the optional account_ids on /balances, /split/preview, /split/create and /split/list limits the call to a subset of the company’s treasury accounts (for example one branch or one currency pool). Auto allocation and re-allocation only use those accounts; manual shares outside the scope are rejected with UNKNOWN_ACCOUNT; balances and lists only cover splits funded from those accounts. Omit it to use the whole organisation’s treasury (default).

{
  "actor_ref": "accountant",
  "counterparty": { "name": "OOO Paxta Trade",
                    "account_number": "2020…4321" },
  "total_amount": 50000000,
  "allocation": { "mode": "auto" },
  "account_ids": ["acc_01J…", "acc_01J…"],
  "idempotency_key": "inv-0418-paxta",
  "reference": "Invoice 0418"
}

{
  "split": {
    "split_id": "split_01J…",
    "status": "completed",
    "counterparty": { "name": "OOO Paxta Trade", "account_mask": "••••4321" },
    "total_amount": 50000000,
    "currency": "UZS",
    "allocation_mode": "auto",
    "created_by": { "member_ref": "accountant",
                    "display_name": "Bekzod (Accountant)",
                    "role": "accountant" },
    "parts": [
      { "part_no": 1, "account_id": "acc_01J…",
        "account_label": "Tumaris · Settlement ••1111",
        "amount": 35000000, "status": "settled",
        "attempts": 1, "payment_id": "pay_01J…" },
      { "part_no": 2, "account_id": "acc_01J…",
        "account_label": "Lochin · Settlement ••2222",
        "amount": 15000000, "status": "settled",
        "attempts": 1, "payment_id": "pay_01J…" }
    ],
    "progress": { "settled": 50000000, "in_flight": 0,
                  "failed": 0, "compensated": 0 }
  }
}

{
  "actor_ref": "accountant",
  "split_id": "split_01J…"
}

{
  "split": {
    "split_id": "split_01J…",
    "status": "completed",
    "counterparty": { "name": "OOO Paxta Trade", "account_mask": "••••4321" },
    "total_amount": 50000000,
    "currency": "UZS",
    "allocation_mode": "auto",
    "created_by": { "member_ref": "accountant",
                    "display_name": "Bekzod (Accountant)",
                    "role": "accountant" },
    "parts": [
      { "part_no": 1, "account_id": "acc_01J…",
        "account_label": "Tumaris · Settlement ••1111",
        "amount": 35000000, "status": "settled",
        "attempts": 1, "payment_id": "pay_01J…" },
      { "part_no": 2, "account_id": "acc_01J…",
        "account_label": "Lochin · Settlement ••2222",
        "amount": 15000000, "status": "settled",
        "attempts": 1, "payment_id": "pay_01J…" }
    ],
    "progress": { "settled": 50000000, "in_flight": 0,
                  "failed": 0, "compensated": 0 }
  }
}

For banks, MFIs, fintechs and marketplaces that ship open banking under their own brand — Open Banking as a Service. Most of it lives in the dashboard: branding, API keys, rate limits, usage analytics and webhooks are managed per organisation, and every change is audited. The API itself is two POST calls: /v1/link/token/create (with an optional sandbox branding override) and /v1/link/branding, which the Link widget calls with its link_token. “Secured by Silkroute” always stays visible on the consent flow.

• Branding: saved per organisation in the dashboard (Branding page; owners, admins and developers) and applied to every Link consent flow. “Preview in Link” shows an unsaved look in a sandbox session and saves nothing. “Secured by Silkroute” always stays visible.
• API keys: created in the dashboard — the secret is shown exactly once and only its hash is stored. Rotate (the old secret stops immediately) or revoke. Keys are sandbox or production; production keys can be created but stay inert in this sandbox build (403 PRODUCTION_NOT_ENABLED). The shared public demo key cannot be rotated, re-limited or revoked (409 PROTECTED_KEY).
• Rate limits and usage: each key has a limit (default 600 a minute, 1–100000). Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; over the limit the call fails with 429 RATE_LIMIT_EXCEEDED and a Retry-After header. The dashboard shows requests per day (ok / client errors / throttled / server errors), error rate, p50 / p95 latency per endpoint, requests and throttles per key, and request logs you can filter by key.
• Webhooks: endpoints belong to your organisation, and each delivery is signed with Silkroute-Signature: sha256=<HMAC-SHA256 of the raw body with your webhook secret> — check it with verifyWebhook from the SDK. A failed delivery is retried with exponential backoff (2^n minutes, capped at 6 h) and then marked dead. In the dashboard, enable or disable endpoints, redeliver an event and send a test event. Every platform change lands in the audit log.

{
  "user_ref": "user_42",
  "products": ["transactions"],
  "branding": {
    "display_name": "NovaPay",
    "primary_color": "#7C3AED",
    "accent_color": "#0B0F19",
    "logo_url": "https://cdn.novapay.uz/logo.svg",
    "support_url": "https://novapay.uz/help",
    "privacy_url": "https://novapay.uz/privacy",
    "consent_headline": "Connect your bank to NovaPay"
  }
}

{
  "link_token": "link-sandbox-3f9a…",
  "expiration": "2026-10-03T10:30:00.000Z"
}

{
  "link_token": "link-sandbox-3f9a…"
}

{
  "branding": {
    "display_name": "NovaPay",
    "logo_url": "https://cdn.novapay.uz/logo.svg",
    "primary_color": "#7C3AED",
    "on_primary_color": "#FFFFFF",
    "accent_color": "#0B0F19",
    "support_url": "https://novapay.uz/help",
    "privacy_url": "https://novapay.uz/privacy",
    "consent_headline": "Connect your bank to NovaPay",
    "secured_by": "Silkroute",
    "source": "preview"
  }
}

Webhooks

We POST signed events to your endpoint. Verify Silkroute-Signature: sha256=… (HMAC-SHA256 over the raw body). Failed deliveries retry with backoff.

Sandbox credentials

Error codes

Errors use the shape { error_type, error_code, error_message, display_message, request_id }.