@finrock/mcp 0.0.0-stage → 1.0.0

package/guides/_client/node.md

@@ -0,0 +1,55 @@
+### Finrock API client (`finrock.ts`)
+
+No SDK needed: this signs each request with Node's built-in `crypto`.
+
+```ts
+// finrock.ts — server-side only. Never import this into browser code.
+import { createHash, createSign, randomUUID } from "node:crypto";
+
+const API_BASE = "https://api.finrock.io";
+const API_KEY = process.env.FINROCK_API_KEY!; // API Key UUID from Finrock Dashboard → API Users
+// PEM of the RSA-4096 private key whose public half you uploaded. Env vars often
+// store newlines as "\n", so restore them.
+const PRIVATE_KEY = process.env.FINROCK_PRIVATE_KEY!.replace(/\\n/g, "\n");
+
+const b64url = (b: Buffer | string) => Buffer.from(b).toString("base64url");
+
+/** A fresh RS256 JWT for one request. Finrock rejects reused nonces and exp > iat + 30s. */
+function signJwt(uri: string, rawBody: string): string {
+  const now = Math.floor(Date.now() / 1000);
+  const header = { alg: "RS256", typ: "JWT" };
+  const payload = {
+    uri, // request path, e.g. /dac/v1/invoice
+    nonce: randomUUID(),
+    iat: now,
+    exp: now + 25,
+    sub: API_KEY,
+    bodyHash: createHash("sha256").update(rawBody).digest("hex"),
+  };
+  const input = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(payload))}`;
+  const signature = createSign("RSA-SHA256").update(input).sign(PRIVATE_KEY);
+  return `${input}.${b64url(signature)}`;
+}
+
+export async function finrock<T = any>(
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
+  path: string,
+  body?: unknown,
+): Promise<T> {
+  // Hash exactly the string you send: serialise once and reuse it.
+  const rawBody = body === undefined ? "" : JSON.stringify(body);
+  const res = await fetch(API_BASE + path, {
+    method,
+    headers: {
+      authorization: `Bearer ${signJwt(path, rawBody)}`,
+      "x-api-key": API_KEY,
+      accept: "application/json",
+      ...(rawBody ? { "content-type": "application/json" } : {}),
+    },
+    body: rawBody || undefined,
+  });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`Finrock ${method} ${path} -> HTTP ${res.status}: ${text}`);
+  return (text ? JSON.parse(text) : null) as T;
+}
+```

package/guides/_client/php.md

@@ -0,0 +1,67 @@
+### Finrock API client (`finrock.php`)
+
+Uses only the `openssl`, `curl` and `json` extensions.
+
+```php
+<?php
+// finrock.php — server-side only.
+const FINROCK_API_BASE = 'https://api.finrock.io';
+
+function finrock_b64url(string $s): string
+{
+    return rtrim(strtr(base64_encode($s), '+/', '-_'), '=');
+}
+
+/** A fresh RS256 JWT for one request. Finrock rejects reused nonces and exp > iat + 30s. */
+function finrock_sign(string $uri, string $rawBody): string
+{
+    $now = time();
+    $header = ['alg' => 'RS256', 'typ' => 'JWT'];
+    $payload = [
+        'uri' => $uri, // request path, e.g. /dac/v1/invoice
+        'nonce' => bin2hex(random_bytes(16)),
+        'iat' => $now,
+        'exp' => $now + 25,
+        'sub' => getenv('FINROCK_API_KEY'), // API Key UUID from Finrock Dashboard -> API Users
+        'bodyHash' => hash('sha256', $rawBody),
+    ];
+    $input = finrock_b64url(json_encode($header)) . '.' . finrock_b64url(json_encode($payload, JSON_UNESCAPED_SLASHES));
+    // PEM of the RSA-4096 private key whose public half you uploaded.
+    $key = openssl_pkey_get_private(str_replace('\n', "\n", getenv('FINROCK_PRIVATE_KEY')));
+    if ($key === false || !openssl_sign($input, $signature, $key, OPENSSL_ALGO_SHA256)) {
+        throw new RuntimeException('Could not sign the Finrock JWT: check FINROCK_PRIVATE_KEY');
+    }
+    return $input . '.' . finrock_b64url($signature);
+}
+
+function finrock(string $method, string $path, ?array $body = null)
+{
+    // Hash exactly the string you send: serialise once and reuse it.
+    $rawBody = $body === null ? '' : json_encode($body, JSON_UNESCAPED_SLASHES);
+    $headers = [
+        'Authorization: Bearer ' . finrock_sign($path, $rawBody),
+        'x-api-key: ' . getenv('FINROCK_API_KEY'),
+        'Accept: application/json',
+    ];
+    if ($rawBody !== '') {
+        $headers[] = 'Content-Type: application/json';
+    }
+    $ch = curl_init(FINROCK_API_BASE . $path);
+    curl_setopt_array($ch, [
+        CURLOPT_CUSTOMREQUEST => $method,
+        CURLOPT_HTTPHEADER => $headers,
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_TIMEOUT => 30,
+    ]);
+    if ($rawBody !== '') {
+        curl_setopt($ch, CURLOPT_POSTFIELDS, $rawBody);
+    }
+    $response = curl_exec($ch);
+    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+    curl_close($ch);
+    if ($response === false || $status >= 400) {
+        throw new RuntimeException("Finrock $method $path -> HTTP $status: $response");
+    }
+    return $response === '' ? null : json_decode($response, true);
+}
+```

package/guides/_client/python.md

@@ -0,0 +1,55 @@
+### Finrock API client (`finrock.py`)
+
+```bash
+pip install "pyjwt[crypto]" requests
+```
+
+```python
+# finrock.py — server-side only.
+import hashlib
+import json
+import os
+import time
+import uuid
+
+import jwt  # PyJWT
+import requests
+
+API_BASE = "https://api.finrock.io"
+API_KEY = os.environ["FINROCK_API_KEY"]  # API Key UUID from Finrock Dashboard -> API Users
+# PEM of the RSA-4096 private key whose public half you uploaded.
+PRIVATE_KEY = os.environ["FINROCK_PRIVATE_KEY"].replace("\\n", "\n")
+
+
+def _sign(uri: str, raw_body: str) -> str:
+    """A fresh RS256 JWT for one request. Finrock rejects reused nonces and exp > iat + 30s."""
+    now = int(time.time())
+    payload = {
+        "uri": uri,  # request path, e.g. /dac/v1/invoice
+        "nonce": str(uuid.uuid4()),
+        "iat": now,
+        "exp": now + 25,
+        "sub": API_KEY,
+        "bodyHash": hashlib.sha256(raw_body.encode("utf-8")).hexdigest(),
+    }
+    return jwt.encode(payload, PRIVATE_KEY, algorithm="RS256")
+
+
+def finrock(method: str, path: str, body=None):
+    # Hash exactly the bytes you send: serialise once and reuse them.
+    raw_body = "" if body is None else json.dumps(body, separators=(",", ":"))
+    headers = {
+        "Authorization": f"Bearer {_sign(path, raw_body)}",
+        "x-api-key": API_KEY,
+        "Accept": "application/json",
+    }
+    if raw_body:
+        headers["Content-Type"] = "application/json"
+    res = requests.request(
+        method, API_BASE + path, data=raw_body.encode("utf-8") if raw_body else None,
+        headers=headers, timeout=30,
+    )
+    if not res.ok:
+        raise RuntimeError(f"Finrock {method} {path} -> HTTP {res.status_code}: {res.text}")
+    return res.json() if res.text else None
+```

package/guides/accept-payments/nextjs.md

@@ -0,0 +1,75 @@
+### Server Action to start checkout (`app/checkout/actions.ts`)
+
+```ts
+"use server";
+import { redirect } from "next/navigation";
+import { finrock } from "@/lib/finrock";
+import { db } from "@/lib/db"; // your data layer
+
+const BASE_URL = process.env.PUBLIC_BASE_URL!; // e.g. https://shop.example.com
+
+export async function payWithCrypto(orderId: string) {
+  const order = await db.orders.get(orderId);
+  const invoice = await finrock("POST", "/dac/v1/invoice", {
+    fiat: { asset_id: order.currency, amount: order.total }, // e.g. "USD", 49.99
+    crypto: { asset_id: "USDT_TRX" }, // the coin to collect; Finrock converts the fiat amount
+    memo: `order-${order.id}`,
+    payer: { email: order.email },
+    ipn_url: `${BASE_URL}/api/finrock/ipn?order=${order.id}`,
+    success_url: `${BASE_URL}/orders/${order.id}/thanks`,
+    failed_url: `${BASE_URL}/orders/${order.id}/payment-failed`,
+  });
+  await db.orders.update(order.id, { finrockInvoiceId: invoice.id, paymentStatus: invoice.status });
+  redirect(invoice.payment_url);
+}
+```
+
+### Shared status check (`lib/sync-invoice.ts`)
+
+```ts
+import "server-only";
+import { finrock } from "@/lib/finrock";
+import { db } from "@/lib/db";
+
+// Re-check the invoice with Finrock instead of trusting the notification or redirect.
+export async function syncInvoice(orderId: string) {
+  const order = await db.orders.get(orderId);
+  if (!order?.finrockInvoiceId) return order;
+  const [invoice] = await finrock("GET", `/dac/v1/invoice?id=${encodeURIComponent(order.finrockInvoiceId)}`);
+  if (invoice?.status === "Paid" && order.paymentStatus !== "Paid") {
+    await db.orders.update(orderId, { paymentStatus: "Paid" });
+    await fulfil(orderId); // must be safe to call twice
+  } else if (invoice && invoice.status !== order.paymentStatus) {
+    await db.orders.update(orderId, { paymentStatus: invoice.status });
+  }
+  return db.orders.get(orderId);
+}
+```
+
+### Notification endpoint (`app/api/finrock/ipn/route.ts`)
+
+```ts
+import { syncInvoice } from "@/lib/sync-invoice";
+
+export const runtime = "nodejs";
+
+export async function POST(req: Request) {
+  const orderId = new URL(req.url).searchParams.get("order");
+  if (orderId) await syncInvoice(orderId);
+  return new Response("ok", { status: 200 });
+}
+```
+
+### Thank-you page (`app/orders/[id]/thanks/page.tsx`)
+
+```tsx
+import { syncInvoice } from "@/lib/sync-invoice";
+
+export default async function Thanks({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const order = await syncInvoice(id);
+  return order.paymentStatus === "Paid"
+    ? <p>Payment received. Thank you!</p>
+    : <p>We are waiting for your payment to confirm on-chain ({order.paymentStatus}).</p>;
+}
+```

package/guides/accept-payments/node.md

@@ -0,0 +1,49 @@
+### Express routes (`server.ts`)
+
+```ts
+import express from "express";
+import { finrock } from "./finrock";
+
+const app = express();
+app.use(express.json());
+const BASE_URL = process.env.PUBLIC_BASE_URL!; // e.g. https://shop.example.com
+
+app.post("/checkout/:orderId/crypto", async (req, res) => {
+  const order = await db.orders.get(req.params.orderId); // your data layer
+  const invoice = await finrock("POST", "/dac/v1/invoice", {
+    fiat: { asset_id: order.currency, amount: order.total }, // e.g. "USD", 49.99
+    crypto: { asset_id: "USDT_TRX" }, // the coin to collect; Finrock converts the fiat amount
+    memo: `order-${order.id}`,
+    payer: { email: order.email },
+    ipn_url: `${BASE_URL}/finrock/ipn?order=${order.id}`,
+    success_url: `${BASE_URL}/orders/${order.id}/thanks`,
+    failed_url: `${BASE_URL}/orders/${order.id}/payment-failed`,
+  });
+  await db.orders.update(order.id, { finrockInvoiceId: invoice.id, paymentStatus: invoice.status });
+  res.redirect(303, invoice.payment_url);
+});
+
+// Re-check the invoice with Finrock instead of trusting the notification body.
+async function syncInvoice(orderId: string) {
+  const order = await db.orders.get(orderId);
+  if (!order?.finrockInvoiceId) return;
+  const [invoice] = await finrock("GET", `/dac/v1/invoice?id=${encodeURIComponent(order.finrockInvoiceId)}`);
+  if (!invoice) return;
+  if (invoice.status === "Paid" && order.paymentStatus !== "Paid") {
+    await db.orders.update(orderId, { paymentStatus: "Paid" });
+    await fulfil(orderId); // must be safe to call twice
+  } else if (invoice.status !== order.paymentStatus) {
+    await db.orders.update(orderId, { paymentStatus: invoice.status });
+  }
+}
+
+app.post("/finrock/ipn", async (req, res) => {
+  await syncInvoice(String(req.query.order));
+  res.sendStatus(200);
+});
+
+app.get("/orders/:orderId/thanks", async (req, res) => {
+  await syncInvoice(req.params.orderId);
+  res.render("thanks", { order: await db.orders.get(req.params.orderId) });
+});
+```

package/guides/accept-payments/overview.md

@@ -0,0 +1,30 @@
+---
+title: Accept a crypto payment with a hosted invoice
+summary: Create an invoice on your server, send the customer to Finrock's hosted payment page, and mark the order paid after re-checking the invoice.
+docs: api-reference/invoicing/create-invoice, api-reference/invoicing/list-invoices, reference/supported-assets
+client: true
+---
+
+This is the simplest way to take crypto payments for an order, subscription or invoice.
+
+### Flow
+
+1. **Customer checks out.** Your server calls `POST /dac/v1/invoice` with the price and a
+   unique `memo` (your order ID works well).
+   - `crypto.asset_id` is always required: the coin to collect, e.g. `crypto: { asset_id: "USDT_TRX" }`
+     (asset IDs come from Supported Assets). Without it the API returns `ASSET_REQUIRED`.
+   - Price in fiat with `fiat: { asset_id: "USD", amount }` and Finrock converts it to the coin, or
+   - give `crypto.amount` to price in the coin directly.
+   - Set `success_url`, `failed_url`, and `ipn_url` (payment notifications).
+2. **Save** the returned invoice `id` against your order, then **redirect** the customer to
+   the returned `payment_url`.
+3. **Confirm payment on your server.** When the `ipn_url` is called, or the customer lands on
+   `success_url`, fetch the invoice with `GET /dac/v1/invoice?id=<invoice id>` and fulfil only
+   when its `status` is `Paid`. Treat the redirect and notification as hints, never as proof.
+4. **Make fulfilment idempotent.** Notifications and redirects can arrive more than once.
+
+Invoice statuses: `Pending`, `Processing`, `Paid`, `Expired`, `Failed`, `Cancelled`, `Refunded`.
+Invoices expire at `expiry_ts`; late payments may need manual reconciliation.
+
+Put your own order ID in the `ipn_url` query string (as below) so the notification handler can
+find the order without depending on the notification body, whose format is not documented yet.

package/guides/accept-payments/php.md

@@ -0,0 +1,61 @@
+### Start checkout (`checkout_crypto.php`)
+
+```php
+<?php
+require __DIR__ . '/finrock.php';
+require __DIR__ . '/db.php'; // your data layer
+
+$baseUrl = getenv('PUBLIC_BASE_URL'); // e.g. https://shop.example.com
+$order = db_get_order($_POST['order_id']);
+
+$invoice = finrock('POST', '/dac/v1/invoice', [
+    'fiat' => ['asset_id' => $order['currency'], 'amount' => (float) $order['total']], // e.g. "USD", 49.99
+    'crypto' => ['asset_id' => 'USDT_TRX'], // the coin to collect; Finrock converts the fiat amount
+    'memo' => 'order-' . $order['id'],
+    'payer' => ['email' => $order['email']],
+    'ipn_url' => "$baseUrl/finrock_ipn.php?order=" . urlencode($order['id']),
+    'success_url' => "$baseUrl/thanks.php?order=" . urlencode($order['id']),
+    'failed_url' => "$baseUrl/payment_failed.php?order=" . urlencode($order['id']),
+]);
+
+db_update_order($order['id'], ['finrock_invoice_id' => $invoice['id'], 'payment_status' => $invoice['status']]);
+header('Location: ' . $invoice['payment_url'], true, 303);
+```
+
+### Shared status check (`sync_invoice.php`)
+
+```php
+<?php
+require_once __DIR__ . '/finrock.php';
+require_once __DIR__ . '/db.php';
+
+// Re-check the invoice with Finrock instead of trusting the notification body.
+function sync_invoice(string $orderId): ?array
+{
+    $order = db_get_order($orderId);
+    if (!$order || empty($order['finrock_invoice_id'])) {
+        return $order;
+    }
+    $invoices = finrock('GET', '/dac/v1/invoice?id=' . rawurlencode($order['finrock_invoice_id'])) ?? [];
+    if ($invoices) {
+        $status = $invoices[0]['status'];
+        if ($status === 'Paid' && $order['payment_status'] !== 'Paid') {
+            db_update_order($orderId, ['payment_status' => 'Paid']);
+            fulfil($orderId); // must be safe to call twice
+        } elseif ($status !== $order['payment_status']) {
+            db_update_order($orderId, ['payment_status' => $status]);
+        }
+    }
+    return db_get_order($orderId);
+}
+```
+
+### Notification endpoint (`finrock_ipn.php`)
+
+```php
+<?php
+require __DIR__ . '/sync_invoice.php';
+sync_invoice($_GET['order'] ?? '');
+http_response_code(200);
+echo 'ok';
+```

package/guides/accept-payments/python.md

@@ -0,0 +1,59 @@
+### FastAPI routes (`main.py`)
+
+```python
+import os
+from urllib.parse import quote
+
+from fastapi import FastAPI
+from fastapi.responses import RedirectResponse
+
+from finrock import finrock
+from mydb import db, fulfil  # your data layer
+
+app = FastAPI()
+BASE_URL = os.environ["PUBLIC_BASE_URL"]  # e.g. https://shop.example.com
+
+
+@app.post("/checkout/{order_id}/crypto")
+def start_crypto_checkout(order_id: str):
+    order = db.get_order(order_id)
+    invoice = finrock("POST", "/dac/v1/invoice", {
+        "fiat": {"asset_id": order.currency, "amount": float(order.total)},  # e.g. "USD", 49.99
+        "crypto": {"asset_id": "USDT_TRX"},  # the coin to collect; Finrock converts the fiat amount
+        "memo": f"order-{order.id}",
+        "payer": {"email": order.email},
+        "ipn_url": f"{BASE_URL}/finrock/ipn?order={order.id}",
+        "success_url": f"{BASE_URL}/orders/{order.id}/thanks",
+        "failed_url": f"{BASE_URL}/orders/{order.id}/payment-failed",
+    })
+    db.update_order(order.id, finrock_invoice_id=invoice["id"], payment_status=invoice["status"])
+    return RedirectResponse(invoice["payment_url"], status_code=303)
+
+
+def sync_invoice(order_id: str):
+    """Re-check the invoice with Finrock instead of trusting the notification body."""
+    order = db.get_order(order_id)
+    if not order or not order.finrock_invoice_id:
+        return order
+    invoices = finrock("GET", f"/dac/v1/invoice?id={quote(order.finrock_invoice_id)}") or []
+    if invoices:
+        status = invoices[0]["status"]
+        if status == "Paid" and order.payment_status != "Paid":
+            db.update_order(order_id, payment_status="Paid")
+            fulfil(order_id)  # must be safe to call twice
+        elif status != order.payment_status:
+            db.update_order(order_id, payment_status=status)
+    return db.get_order(order_id)
+
+
+@app.post("/finrock/ipn")
+def finrock_ipn(order: str):
+    sync_invoice(order)
+    return {"ok": True}
+
+
+@app.get("/orders/{order_id}/thanks")
+def thanks(order_id: str):
+    order = sync_invoice(order_id)
+    return {"status": order.payment_status}
+```

package/guides/authentication/overview.md

@@ -0,0 +1,60 @@
+---
+title: Authenticate with the Finrock API
+summary: Create an API user, generate an RSA key pair, and sign every request with a short-lived JWT.
+docs: quickstart, api-reference/authentication, guides/whitelist-ips, reference/http-status-codes
+client: true
+---
+
+Every Finrock API call (except the public utilities such as Supported Assets and Asset Price)
+needs two headers:
+
+- `x-api-key`: the API Key UUID of an API user.
+- `Authorization: Bearer <JWT>`: a JWT signed with **RS256** using your own RSA-4096 private key.
+
+### One-time setup
+
+1. Generate a key pair. The private key never leaves your servers.
+   ```bash
+   openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096 -out finrock_private.pem
+   openssl pkey -in finrock_private.pem -pubout -out finrock_public.pem
+   ```
+2. In the Finrock Dashboard, open **API Users**, create a user, upload `finrock_public.pem`
+   and copy the API Key UUID (it is shown only once).
+3. Store both as server-side secrets:
+   ```bash
+   FINROCK_API_KEY=4466c45a-...           # the API Key UUID
+   FINROCK_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
+   ```
+4. Optional but recommended: restrict the key to your server IPs (see *Whitelist IPs*).
+
+### Rules for the JWT
+
+| Claim | Value |
+|---|---|
+| `uri` | The request path, e.g. `/dac/v1/invoice` |
+| `nonce` | A new random value (UUID) for every request; reuse is rejected |
+| `iat` | Now, in seconds since the epoch |
+| `exp` | At most `iat + 30`; use `iat + 25` to allow for clock skew |
+| `sub` | Your API Key UUID |
+| `bodyHash` | Hex SHA-256 of the exact raw body string you send (`""` when there is no body) |
+
+Build a new JWT for every request. Serialise the body once, hash that exact string, and send
+that same string; pretty-printing or re-serialising after hashing causes a `bodyHash mismatch` 401.
+
+### Never do this
+
+- Never call the Finrock API from browser or mobile code; the private key and API key would leak.
+  Browsers use the Payment Widget or a hosted invoice `payment_url` instead.
+- Never commit `finrock_private.pem` or put it in client-side environment variables
+  (`NEXT_PUBLIC_*`, `VITE_*`, and so on).
+
+### Troubleshooting 401s
+
+- *Token expired or window too large*: server clock drift, or `exp` more than 30 s after `iat`.
+- *Invalid signature*: wrong algorithm (must be RS256) or the uploaded public key doesn't match.
+- *bodyHash mismatch*: the body sent differs from the string that was hashed.
+- *Nonce already used*: a JWT was reused, e.g. on a retry. Sign again for each attempt.
+
+> Open question to confirm with Finrock: for GET requests with a query string, this client signs
+> the path including the query (e.g. `/dac/v1/invoice?id=...`). If you get a signature 401 on
+> such a call, try signing the path without the query string.

package/guides/deposit-addresses/nextjs.md

@@ -0,0 +1,50 @@
+### Address provisioning (`deposit-addresses.ts`)
+
+```ts
+import { finrock } from "@/lib/finrock";
+
+// One-time setup per asset (run from a script). Errors if the wallet already exists.
+export async function createWallet(asset: string) {
+  return finrock("POST", "/dac/v1/wallet", { asset });
+}
+
+// Get or create the deposit address for a customer and asset.
+export async function depositAddressFor(customerId: string, asset: string) {
+  const existing = await db.depositAddresses.find({ customerId, asset }); // your data layer
+  if (existing) return existing;
+
+  const created = await finrock("POST", "/dac/v1/generate-address", {
+    asset,                       // e.g. "USDT_TRX"
+    label: `customer-${customerId}`,
+    omnibus: false,
+    auto_refill: true,
+  });
+  return db.depositAddresses.insert({
+    customerId,
+    asset,
+    address: created.address,
+    addressTag: created.address_tag, // needed for XRP / XLM
+    label: created.label,
+  });
+}
+```
+
+### Show it to the customer (`app/wallet/[asset]/page.tsx`)
+
+```tsx
+import { depositAddressFor } from "@/lib/deposit-addresses";
+import { getCurrentUser } from "@/lib/auth"; // your auth
+
+export default async function DepositPage({ params }: { params: Promise<{ asset: string }> }) {
+  const { asset } = await params;
+  const user = await getCurrentUser();
+  const addr = await depositAddressFor(user.id, asset);
+  return (
+    <div>
+      <p>Send only {asset} to this address:</p>
+      <code>{addr.address}</code>
+      {addr.addressTag && <p>Destination tag / memo: <code>{addr.addressTag}</code></p>}
+    </div>
+  );
+}
+```

package/guides/deposit-addresses/node.md

@@ -0,0 +1,30 @@
+### Address provisioning (`deposit-addresses.ts`)
+
+```ts
+import { finrock } from "./finrock";
+
+// One-time setup per asset (run from a script). Errors if the wallet already exists.
+export async function createWallet(asset: string) {
+  return finrock("POST", "/dac/v1/wallet", { asset });
+}
+
+// Get or create the deposit address for a customer and asset.
+export async function depositAddressFor(customerId: string, asset: string) {
+  const existing = await db.depositAddresses.find({ customerId, asset }); // your data layer
+  if (existing) return existing;
+
+  const created = await finrock("POST", "/dac/v1/generate-address", {
+    asset,                       // e.g. "USDT_TRX"
+    label: `customer-${customerId}`,
+    omnibus: false,
+    auto_refill: true,
+  });
+  return db.depositAddresses.insert({
+    customerId,
+    asset,
+    address: created.address,
+    addressTag: created.address_tag, // needed for XRP / XLM
+    label: created.label,
+  });
+}
+```

package/guides/deposit-addresses/overview.md

@@ -0,0 +1,36 @@
+---
+title: Give each customer a crypto deposit address
+summary: Create one wallet per asset, generate a labelled deposit address per customer, and credit them from Deposit webhooks.
+docs: guides/create-wallet-address, api-reference/wallets/create-wallet, api-reference/wallets/create-address, concepts/omnibus-wallets, concepts/gas-tanks, reference/supported-assets
+client: true
+---
+
+Use this for top-ups, exchange-style balances, or any app where customers send crypto to an
+address that belongs to them.
+
+### Flow
+
+1. **One-time: create a wallet per asset** with `POST /dac/v1/wallet` `{ "asset": "USDT_TRX" }`.
+   A sub-account can hold only one wallet per asset, so creating it twice errors. Do this
+   once from a setup script or the dashboard, not on every request.
+2. **Per customer: generate an address** with `POST /dac/v1/generate-address`:
+   - `asset`: the asset name, e.g. `USDT_TRX`, `ETH`, `BTC`.
+   - `label`: your customer ID (e.g. `customer-42`) so deposits can be reconciled.
+   - `omnibus`: `false` (default) keeps an isolated address; `true` adds it to the shared pool.
+   - `auto_refill`: `true` tops up gas from your Gas Tank when needed (always on for omnibus).
+3. **Store** the returned `address` (and `address_tag`, which XRP/XLM need as a destination tag)
+   with the customer and show it to them, ideally with a QR code.
+4. **Credit deposits from webhooks** (see the `webhooks` guide): on a `Deposit` event with
+   status `Success`, find the customer by the deposit address or label, then credit `amount`
+   once per event `id`.
+
+### Choosing omnibus vs isolated
+
+- **Isolated** keeps each customer's funds on their own address: clean per-customer audit trail,
+  but each address needs gas to move funds on EVM/Tron chains (Gas Tanks handle this).
+- **Omnibus** pools deposits for simpler treasury management and is typical for high volume.
+
+Read *Omnibus vs Isolated Addresses* and *Gas Tanks* before choosing for production.
+
+> Confirm with a test deposit which webhook fields carry your address and label
+> (`dest_id` / `dest_alias` in the samples) before relying on them for crediting.

package/guides/deposit-addresses/php.md

@@ -0,0 +1,35 @@
+### Address provisioning (`deposit_addresses.php`)
+
+```php
+<?php
+require_once __DIR__ . '/finrock.php';
+require_once __DIR__ . '/db.php'; // your data layer
+
+// One-time setup per asset (run from a script). Errors if the wallet already exists.
+function create_wallet(string $asset): array
+{
+    return finrock('POST', '/dac/v1/wallet', ['asset' => $asset]);
+}
+
+// Get or create the deposit address for a customer and asset.
+function deposit_address_for(string $customerId, string $asset): array
+{
+    $existing = db_find_deposit_address($customerId, $asset);
+    if ($existing) {
+        return $existing;
+    }
+    $created = finrock('POST', '/dac/v1/generate-address', [
+        'asset' => $asset, // e.g. "USDT_TRX"
+        'label' => "customer-$customerId",
+        'omnibus' => false,
+        'auto_refill' => true,
+    ]);
+    return db_insert_deposit_address([
+        'customer_id' => $customerId,
+        'asset' => $asset,
+        'address' => $created['address'],
+        'address_tag' => $created['address_tag'] ?? null, // needed for XRP / XLM
+        'label' => $created['label'],
+    ]);
+}
+```