@finrock/mcp 0.0.0-stage → 0.1.0

package/guides/deposit-addresses/python.md

@@ -0,0 +1,31 @@
+### Address provisioning (`deposit_addresses.py`)
+
+```python
+from finrock import finrock
+from mydb import db  # your data layer
+
+
+def create_wallet(asset: str):
+    """One-time setup per asset (run from a script). Errors if the wallet already exists."""
+    return finrock("POST", "/dac/v1/wallet", {"asset": asset})
+
+
+def deposit_address_for(customer_id: str, asset: str):
+    """Get or create the deposit address for a customer and asset."""
+    existing = db.find_deposit_address(customer_id, asset)
+    if existing:
+        return existing
+    created = finrock("POST", "/dac/v1/generate-address", {
+        "asset": asset,  # e.g. "USDT_TRX"
+        "label": f"customer-{customer_id}",
+        "omnibus": False,
+        "auto_refill": True,
+    })
+    return db.insert_deposit_address(
+        customer_id=customer_id,
+        asset=asset,
+        address=created["address"],
+        address_tag=created.get("address_tag"),  # needed for XRP / XLM
+        label=created["label"],
+    )
+```

package/guides/payment-widget/html.md

@@ -0,0 +1,26 @@
+### Plain HTML (works with any backend)
+
+```html
+<div id="finrock-widget"></div>
+<script src="https://finrock.io/widget/widget.js"></script>
+<script>
+  loadWidget({
+    widget_id: "YOUR_WIDGET_ID",
+    fiat_amount: 49.99,
+    crypto_asset: "USDT_TRX",
+    payer_email: "jane@example.com",
+    desc: "order-1042",
+  }).then(
+    (result) => {
+      // UX only: your server confirms the payment from the webhook.
+      window.location.href = "/orders/1042/thanks";
+    },
+    (err) => {
+      console.error("Payment failed or cancelled", err);
+    },
+  );
+</script>
+```
+
+Render the order values (`fiat_amount`, `desc`, `payer_email`) from your server-side template,
+escaped for JavaScript.

package/guides/payment-widget/nextjs.md

@@ -0,0 +1,41 @@
+### Client component (`components/finrock-widget.tsx`)
+
+```tsx
+"use client";
+import Script from "next/script";
+import { useRouter } from "next/navigation";
+import { useEffect, useState } from "react";
+
+declare global {
+  interface Window {
+    loadWidget?: (opts: Record<string, unknown>) => Promise<unknown>;
+  }
+}
+
+export function FinrockWidget(props: { orderId: string; amount: number; asset?: string; email?: string }) {
+  const router = useRouter();
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    if (!ready || !window.loadWidget) return;
+    window
+      .loadWidget({
+        widget_id: process.env.NEXT_PUBLIC_FINROCK_WIDGET_ID, // the widget ID is safe to expose
+        fiat_amount: props.amount,
+        crypto_asset: props.asset,
+        payer_email: props.email,
+        desc: `order-${props.orderId}`,
+      })
+      // UX only: your server confirms the payment from the webhook.
+      .then(() => router.push(`/orders/${props.orderId}/thanks`))
+      .catch((err) => console.error("Payment failed or cancelled", err));
+  }, [ready, props.amount, props.asset, props.email, props.orderId, router]);
+
+  return (
+    <>
+      <Script src="https://finrock.io/widget/widget.js" strategy="afterInteractive" onReady={() => setReady(true)} />
+      <div id="finrock-widget" />
+    </>
+  );
+}
+```

package/guides/payment-widget/overview.md

@@ -0,0 +1,32 @@
+---
+title: Embed the Finrock payment widget
+summary: Add a drop-in crypto checkout form to any web page with one script tag and a widget ID; no API keys in the browser.
+docs: guides/payment-widget, reference/supported-assets
+client: false
+---
+
+The widget is the fastest way to accept crypto on a website. It needs only a **widget ID**
+from the Finrock dashboard (ask your account manager if you don't see one); no API key,
+private key or server code is required to show it.
+
+### Options for `loadWidget()`
+
+| Option | Type | Purpose |
+|---|---|---|
+| `widget_id` | string | **Required.** Your workspace widget ID |
+| `fiat_amount` | number | Pre-fill the amount in local currency, e.g. `50.00` |
+| `crypto_amount` | number | Pre-fill the crypto amount, e.g. `0.001` |
+| `crypto_asset` | string | Pre-select the coin, e.g. `BTC`, `ETH`, `USDT_TRX` |
+| `payer_name` / `payer_email` / `payer_mobile` | string / string / number | Pre-fill payer details |
+| `desc` | string | Note to you, e.g. your order or invoice number |
+
+`loadWidget()` returns a Promise: it resolves with the payment result and rejects on failure
+or cancellation.
+
+### Important
+
+- Treat the browser callback as a UX signal only. Confirm the payment on your server from a
+  verified webhook (see the `webhooks` guide) before fulfilling, and put your order ID in `desc`
+  so you can match it.
+- If you need per-order amounts that customers can't edit, or a redirect-based flow, use the
+  `accept-payments` (hosted invoice) guide instead.

package/guides/webhooks/nextjs.md

@@ -0,0 +1,48 @@
+### Route Handler (`app/api/webhooks/finrock/route.ts`)
+
+```ts
+import { createPublicKey, verify, constants } from "node:crypto";
+import { db } from "@/lib/db"; // your data layer
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+// Finrock's webhook signing key (https://apidocs.finrock.io/guides/webhooks)
+const FINROCK_WEBHOOK_KEY = createPublicKey(`-----BEGIN PUBLIC KEY-----
+MIIBnzANBgkqhkiG9w0BAQEFAAOCAYwAMIIBhwKCAX4Aq1O7ztZxzkgDCFlUnHvs
+EBffqmlng9uEmNMCGbCpxB7991WiR4TRRVaTUrLxIzPWl79xT6R2Xzba1GqN2bin
+sPBU/cmHEF5v1bDopZ7oHnU43tnlpH1kSOjtvTBORf6v6+9xh87OYtg4wXuwVzCq
+ykXDRPIIzgPCSpA7l7DtPqhOpm0OVpUnVJQ5DgnsMfJMPkrrPTjRkpFZ1RbtqoLW
+UI+bMWZAAKLEsh4Q+SRO7xiHj26gToD+/ZrEAbC/SOcy2ChDfpQ39XN/bYTu52j8
+ndAS/R4qnffLGpmTcxr19UC+BPs5Wb5kx2ZJsGPQPpoPHaTBC1n3YwQlksgeHEvX
+ZBsDoAvIXpGfBjUPzd8bvz5vyxbLYA4lSqp/Fw48NYgRRgfOWjmtqVI07jnXKxU2
+kcQc7QkoFVDYw45DS14tkrsCOJjMF0qux2dL9Gr1z/Xdaod+SyeRqsTDYhbzaD+v
+UkO6chtsIHmQwAF8jYajAR7uKROX+6f8ZIwYDco3AgMBAAE=
+-----END PUBLIC KEY-----`);
+
+export async function POST(req: Request) {
+  // Read raw bytes; don't call req.json() before verifying.
+  const raw = Buffer.from(await req.arrayBuffer());
+  const signature = req.headers.get("x-signature") ?? "";
+  const ok = verify(
+    "sha512",
+    raw,
+    { key: FINROCK_WEBHOOK_KEY, padding: constants.RSA_PKCS1_PADDING },
+    Buffer.from(signature, "base64"),
+  );
+  if (!ok) return new Response("invalid signature", { status: 401 });
+
+  const event = JSON.parse(raw.toString("utf8"));
+
+  // Deduplicate: retries resend the same event, and each status change is its own event.
+  const firstTime = await db.webhookEvents.insertIfAbsent(`${event.id}:${event.status}`);
+  if (!firstTime) return new Response("ok");
+
+  if (event.type === "Deposit" && event.status === "Success") {
+    await creditDeposit(event); // your logic, in a transaction
+  } else if (event.type === "Withdraw") {
+    await db.withdrawals.updateBySequenceId(event.sequence_id, { status: event.status, hash: event.hash });
+  }
+  return new Response("ok");
+}
+```

package/guides/webhooks/node.md

@@ -0,0 +1,48 @@
+### Express endpoint (`webhooks.ts`)
+
+```ts
+import express from "express";
+import { createPublicKey, verify, constants } from "node:crypto";
+
+// Finrock's webhook signing key (https://apidocs.finrock.io/guides/webhooks)
+const FINROCK_WEBHOOK_KEY = createPublicKey(`-----BEGIN PUBLIC KEY-----
+MIIBnzANBgkqhkiG9w0BAQEFAAOCAYwAMIIBhwKCAX4Aq1O7ztZxzkgDCFlUnHvs
+EBffqmlng9uEmNMCGbCpxB7991WiR4TRRVaTUrLxIzPWl79xT6R2Xzba1GqN2bin
+sPBU/cmHEF5v1bDopZ7oHnU43tnlpH1kSOjtvTBORf6v6+9xh87OYtg4wXuwVzCq
+ykXDRPIIzgPCSpA7l7DtPqhOpm0OVpUnVJQ5DgnsMfJMPkrrPTjRkpFZ1RbtqoLW
+UI+bMWZAAKLEsh4Q+SRO7xiHj26gToD+/ZrEAbC/SOcy2ChDfpQ39XN/bYTu52j8
+ndAS/R4qnffLGpmTcxr19UC+BPs5Wb5kx2ZJsGPQPpoPHaTBC1n3YwQlksgeHEvX
+ZBsDoAvIXpGfBjUPzd8bvz5vyxbLYA4lSqp/Fw48NYgRRgfOWjmtqVI07jnXKxU2
+kcQc7QkoFVDYw45DS14tkrsCOJjMF0qux2dL9Gr1z/Xdaod+SyeRqsTDYhbzaD+v
+UkO6chtsIHmQwAF8jYajAR7uKROX+6f8ZIwYDco3AgMBAAE=
+-----END PUBLIC KEY-----`);
+
+export const webhooks = express.Router();
+
+// express.raw keeps the exact bytes; never put express.json() in front of this route.
+webhooks.post("/webhooks/finrock", express.raw({ type: "*/*", limit: "1mb" }), async (req, res) => {
+  const signature = req.header("x-signature") ?? "";
+  const raw: Buffer = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
+  const ok = verify(
+    "sha512",
+    raw,
+    { key: FINROCK_WEBHOOK_KEY, padding: constants.RSA_PKCS1_PADDING },
+    Buffer.from(signature, "base64"),
+  );
+  if (!ok) return res.status(401).send("invalid signature");
+
+  const event = JSON.parse(raw.toString("utf8"));
+
+  // Deduplicate: retries resend the same event, and each status change is its own event.
+  const firstTime = await db.webhookEvents.insertIfAbsent(`${event.id}:${event.status}`);
+  if (!firstTime) return res.sendStatus(200);
+
+  if (event.type === "Deposit" && event.status === "Success") {
+    // Find the customer from the deposit address/label you created for them.
+    await creditDeposit(event); // your logic, in a transaction
+  } else if (event.type === "Withdraw") {
+    await db.withdrawals.updateBySequenceId(event.sequence_id, { status: event.status, hash: event.hash });
+  }
+  res.sendStatus(200);
+});
+```

package/guides/webhooks/overview.md

@@ -0,0 +1,34 @@
+---
+title: Receive and verify Finrock webhooks
+summary: Get real-time deposit and withdrawal events, verify the x-signature header, and process each event exactly once.
+docs: guides/webhooks, reference/transaction-statuses, reference/transaction-types
+client: false
+---
+
+Finrock POSTs a JSON event to your endpoint whenever a deposit arrives or a withdrawal changes
+status. Register the URL at **https://finrock.io/webhooks** (enter the URL, press **+**).
+
+### Rules
+
+1. **Verify every request.** The `x-signature` header is a base64 RSA-SHA512 (PKCS#1 v1.5)
+   signature of the raw body, made with Finrock's key. The public key is in the code below.
+2. **Verify the raw bytes.** Read the body *before* any JSON middleware touches it
+   (`express.raw()`, `await req.arrayBuffer()`, `await request.body()`, `php://input`).
+3. **Return HTTP 200 quickly.** Anything else, or a timeout, is retried up to 5 times
+   (after 30 s, 60 s, 90 s, 120 s, 180 s). Do slow work in a queue.
+4. **Be idempotent.** The same event can arrive more than once, and one transaction sends one
+   event per status change. Deduplicate on `id` + `status`.
+5. **Act on terminal statuses.** Credit a deposit only when `status` is `Success`. `Failed`,
+   `Rejected`, `Blocked`, `UserCancelled` and `AML_Blocked` are also final; everything else
+   (`Pending`, `Processing`, `Signing`, `SweepPending`, `NeedsApproval`, `AML_Pending`) is in progress.
+
+### Useful payload fields
+
+`id`, `type` (`Deposit` or `Withdraw`), `asset` (e.g. `USDT_TRX`), `amount`, `amount_in_usd`,
+`nett` (after fees, negative for withdrawals), `status`, `confirmations.{required,actual}`,
+`hash`, `explorer_url`, `sequence_id` (your idempotency key for withdrawals),
+`source_*`/`dest_*` (type, id, alias), `aml.cid`, `created_timestamp_utc`.
+
+To test locally, expose your endpoint with a tunnel (for example `cloudflared` or `ngrok`) and
+register the tunnel URL. The `verify_webhook_signature` tool on this server can check a captured
+body and signature for you.

package/guides/webhooks/php.md

@@ -0,0 +1,46 @@
+### Endpoint (`finrock_webhook.php`)
+
+```php
+<?php
+require __DIR__ . '/db.php'; // your data layer
+
+// Finrock's webhook signing key (https://apidocs.finrock.io/guides/webhooks)
+const FINROCK_WEBHOOK_KEY = <<<PEM
+-----BEGIN PUBLIC KEY-----
+MIIBnzANBgkqhkiG9w0BAQEFAAOCAYwAMIIBhwKCAX4Aq1O7ztZxzkgDCFlUnHvs
+EBffqmlng9uEmNMCGbCpxB7991WiR4TRRVaTUrLxIzPWl79xT6R2Xzba1GqN2bin
+sPBU/cmHEF5v1bDopZ7oHnU43tnlpH1kSOjtvTBORf6v6+9xh87OYtg4wXuwVzCq
+ykXDRPIIzgPCSpA7l7DtPqhOpm0OVpUnVJQ5DgnsMfJMPkrrPTjRkpFZ1RbtqoLW
+UI+bMWZAAKLEsh4Q+SRO7xiHj26gToD+/ZrEAbC/SOcy2ChDfpQ39XN/bYTu52j8
+ndAS/R4qnffLGpmTcxr19UC+BPs5Wb5kx2ZJsGPQPpoPHaTBC1n3YwQlksgeHEvX
+ZBsDoAvIXpGfBjUPzd8bvz5vyxbLYA4lSqp/Fw48NYgRRgfOWjmtqVI07jnXKxU2
+kcQc7QkoFVDYw45DS14tkrsCOJjMF0qux2dL9Gr1z/Xdaod+SyeRqsTDYhbzaD+v
+UkO6chtsIHmQwAF8jYajAR7uKROX+6f8ZIwYDco3AgMBAAE=
+-----END PUBLIC KEY-----
+PEM;
+
+$raw = file_get_contents('php://input'); // exact bytes
+$signature = base64_decode($_SERVER['HTTP_X_SIGNATURE'] ?? '', true);
+
+if ($signature === false || openssl_verify($raw, $signature, FINROCK_WEBHOOK_KEY, OPENSSL_ALGO_SHA512) !== 1) {
+    http_response_code(401);
+    exit('invalid signature');
+}
+
+$event = json_decode($raw, true);
+
+// Deduplicate: retries resend the same event, and each status change is its own event.
+if (!db_insert_webhook_event_if_absent($event['id'] . ':' . $event['status'])) {
+    http_response_code(200);
+    exit('ok');
+}
+
+if ($event['type'] === 'Deposit' && $event['status'] === 'Success') {
+    credit_deposit($event); // your logic, in a transaction
+} elseif ($event['type'] === 'Withdraw') {
+    db_update_withdrawal($event['sequence_id'] ?? null, $event['status'], $event['hash'] ?? null);
+}
+
+http_response_code(200);
+echo 'ok';
+```

package/guides/webhooks/python.md

@@ -0,0 +1,55 @@
+### FastAPI endpoint (`webhooks.py`)
+
+```bash
+pip install cryptography
+```
+
+```python
+import base64
+import binascii
+import json
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding
+from fastapi import APIRouter, Request, Response
+
+from mydb import db, credit_deposit  # your data layer
+
+# Finrock's webhook signing key (https://apidocs.finrock.io/guides/webhooks)
+FINROCK_WEBHOOK_KEY = serialization.load_pem_public_key(b"""-----BEGIN PUBLIC KEY-----
+MIIBnzANBgkqhkiG9w0BAQEFAAOCAYwAMIIBhwKCAX4Aq1O7ztZxzkgDCFlUnHvs
+EBffqmlng9uEmNMCGbCpxB7991WiR4TRRVaTUrLxIzPWl79xT6R2Xzba1GqN2bin
+sPBU/cmHEF5v1bDopZ7oHnU43tnlpH1kSOjtvTBORf6v6+9xh87OYtg4wXuwVzCq
+ykXDRPIIzgPCSpA7l7DtPqhOpm0OVpUnVJQ5DgnsMfJMPkrrPTjRkpFZ1RbtqoLW
+UI+bMWZAAKLEsh4Q+SRO7xiHj26gToD+/ZrEAbC/SOcy2ChDfpQ39XN/bYTu52j8
+ndAS/R4qnffLGpmTcxr19UC+BPs5Wb5kx2ZJsGPQPpoPHaTBC1n3YwQlksgeHEvX
+ZBsDoAvIXpGfBjUPzd8bvz5vyxbLYA4lSqp/Fw48NYgRRgfOWjmtqVI07jnXKxU2
+kcQc7QkoFVDYw45DS14tkrsCOJjMF0qux2dL9Gr1z/Xdaod+SyeRqsTDYhbzaD+v
+UkO6chtsIHmQwAF8jYajAR7uKROX+6f8ZIwYDco3AgMBAAE=
+-----END PUBLIC KEY-----""")
+
+router = APIRouter()
+
+
+@router.post("/webhooks/finrock")
+async def finrock_webhook(request: Request):
+    raw = await request.body()  # exact bytes; don't use request.json() before verifying
+    try:
+        signature = base64.b64decode(request.headers.get("x-signature", ""), validate=True)
+        FINROCK_WEBHOOK_KEY.verify(signature, raw, padding.PKCS1v15(), hashes.SHA512())
+    except (InvalidSignature, binascii.Error, ValueError):
+        return Response("invalid signature", status_code=401)
+
+    event = json.loads(raw)
+
+    # Deduplicate: retries resend the same event, and each status change is its own event.
+    if not db.insert_webhook_event_if_absent(f"{event['id']}:{event['status']}"):
+        return Response("ok")
+
+    if event["type"] == "Deposit" and event["status"] == "Success":
+        credit_deposit(event)  # your logic, in a transaction
+    elif event["type"] == "Withdraw":
+        db.update_withdrawal(event.get("sequence_id"), status=event["status"], tx_hash=event.get("hash"))
+    return Response("ok")
+```

package/guides/withdrawals/nextjs.md

@@ -0,0 +1,35 @@
+### Payouts (`payouts.ts`)
+
+```ts
+import { finrock } from "@/lib/finrock";
+
+const TERMINAL = new Set(["Success", "Failed", "Rejected", "Blocked", "UserCancelled", "AML_Blocked"]);
+
+export async function sendPayout(p: {
+  payoutId: string;   // your unique ID; becomes Finrock's sequence_id
+  customerId: string;
+  asset: string;      // e.g. "USDT_TRX"
+  amount: number;     // native units
+  address: string;
+  tag?: string;       // XRP / XLM destination tag
+}) {
+  const tx = await finrock("POST", "/dac/v1/transaction", {
+    asset: p.asset,
+    amount: p.amount,
+    source_type: "INTERNAL",
+    destination_type: "EXTERNAL",
+    destination_id: p.address,
+    ...(p.tag ? { destination_tag: p.tag } : {}),
+    sequence_id: p.payoutId, // safe to retry: same ID returns the same transaction
+    aml_cid: p.customerId,
+    memo: `payout-${p.payoutId}`,
+  });
+  await db.payouts.update(p.payoutId, { finrockId: tx.id, status: tx.status });
+  return tx;
+}
+
+export const isTerminal = (status: string) => TERMINAL.has(status);
+```
+
+Prefer webhooks (`Withdraw` events carry your `sequence_id`) to update the payout status.
+If you must poll, back off from 5 s to 60 s and stop at a terminal status.

package/guides/withdrawals/node.md

@@ -0,0 +1,35 @@
+### Payouts (`payouts.ts`)
+
+```ts
+import { finrock } from "./finrock";
+
+const TERMINAL = new Set(["Success", "Failed", "Rejected", "Blocked", "UserCancelled", "AML_Blocked"]);
+
+export async function sendPayout(p: {
+  payoutId: string;   // your unique ID; becomes Finrock's sequence_id
+  customerId: string;
+  asset: string;      // e.g. "USDT_TRX"
+  amount: number;     // native units
+  address: string;
+  tag?: string;       // XRP / XLM destination tag
+}) {
+  const tx = await finrock("POST", "/dac/v1/transaction", {
+    asset: p.asset,
+    amount: p.amount,
+    source_type: "INTERNAL",
+    destination_type: "EXTERNAL",
+    destination_id: p.address,
+    ...(p.tag ? { destination_tag: p.tag } : {}),
+    sequence_id: p.payoutId, // safe to retry: same ID returns the same transaction
+    aml_cid: p.customerId,
+    memo: `payout-${p.payoutId}`,
+  });
+  await db.payouts.update(p.payoutId, { finrockId: tx.id, status: tx.status });
+  return tx;
+}
+
+export const isTerminal = (status: string) => TERMINAL.has(status);
+```
+
+Prefer webhooks (`Withdraw` events carry your `sequence_id`) to update the payout status.
+If you must poll, back off from 5 s to 60 s and stop at a terminal status.

package/guides/withdrawals/overview.md

@@ -0,0 +1,32 @@
+---
+title: Send crypto payouts and withdrawals
+summary: Validate the address, create an idempotent transaction, and track it to a terminal status.
+docs: guides/send-transaction, api-reference/transactions/create-transaction, api-reference/transactions/estimate-fee, api-reference/wallets/validate-address, reference/transaction-statuses, reference/transaction-types, reference/idempotency, guides/ad-hoc-addresses
+client: true
+---
+
+### Flow
+
+1. **Validate the destination** with *Validate Address* before accepting it from a user.
+2. **Optionally estimate the fee** with *Estimate Fee* and show it to the user.
+3. **Create the transaction** with `POST /dac/v1/transaction`:
+   - `asset`, `amount` (native units, up to 8 decimals)
+   - `source_type`: `INTERNAL` (your wallet) or `EXCHANGE`
+   - `destination_type`: `EXTERNAL` for a customer's address (`INTERNAL`, `SUBACCOUNT`, `EXCHANGE` for your own)
+   - `destination_id`: the address; add `destination_tag` for XRP/XLM
+   - `sequence_id`: **always set this** to your own payout ID. If you retry with the same
+     `sequence_id`, Finrock returns the existing transaction instead of paying twice.
+   - `aml_cid`: your customer ID; required when AML screening is enabled.
+4. **Track it** by webhook (preferred) or by polling the transaction with backoff
+   (5 s doubling to 60 s) until a terminal status:
+   `Success`, `Failed`, `Rejected`, `Blocked`, `UserCancelled`, `AML_Blocked`.
+   `NeedsApproval` and `AML_Pending` mean wait; never resubmit with a new `sequence_id`.
+
+### Before going live
+
+- Withdrawals to non-whitelisted addresses need *Ad-Hoc Addresses* enabled, and withdrawals to
+  smart contracts are blocked by default (see *Contract Addresses*).
+- Debit the user's balance in the same database transaction that records the payout, and
+  refund it only on a terminal failure status.
+- Bulk payouts on UTXO chains (BTC etc.) can use `destinations: [{ address, amount }, ...]`
+  instead of `destination_id`.

package/guides/withdrawals/php.md

@@ -0,0 +1,37 @@
+### Payouts (`payouts.php`)
+
+```php
+<?php
+require_once __DIR__ . '/finrock.php';
+require_once __DIR__ . '/db.php'; // your data layer
+
+const FINROCK_TERMINAL = ['Success', 'Failed', 'Rejected', 'Blocked', 'UserCancelled', 'AML_Blocked'];
+
+function send_payout(string $payoutId, string $customerId, string $asset, float $amount, string $address, ?string $tag = null): array
+{
+    $body = [
+        'asset' => $asset, // e.g. "USDT_TRX"
+        'amount' => $amount, // native units
+        'source_type' => 'INTERNAL',
+        'destination_type' => 'EXTERNAL',
+        'destination_id' => $address,
+        'sequence_id' => $payoutId, // safe to retry: same ID returns the same transaction
+        'aml_cid' => $customerId,
+        'memo' => "payout-$payoutId",
+    ];
+    if ($tag !== null) {
+        $body['destination_tag'] = $tag; // XRP / XLM
+    }
+    $tx = finrock('POST', '/dac/v1/transaction', $body);
+    db_update_payout($payoutId, ['finrock_id' => $tx['id'], 'status' => $tx['status']]);
+    return $tx;
+}
+
+function is_terminal(string $status): bool
+{
+    return in_array($status, FINROCK_TERMINAL, true);
+}
+```
+
+Prefer webhooks (`Withdraw` events carry your `sequence_id`) to update the payout status.
+If you must poll, back off from 5 s to 60 s and stop at a terminal status.

package/guides/withdrawals/python.md

@@ -0,0 +1,33 @@
+### Payouts (`payouts.py`)
+
+```python
+from finrock import finrock
+from mydb import db  # your data layer
+
+TERMINAL = {"Success", "Failed", "Rejected", "Blocked", "UserCancelled", "AML_Blocked"}
+
+
+def send_payout(payout_id: str, customer_id: str, asset: str, amount: float, address: str, tag: str | None = None):
+    body = {
+        "asset": asset,  # e.g. "USDT_TRX"
+        "amount": amount,  # native units
+        "source_type": "INTERNAL",
+        "destination_type": "EXTERNAL",
+        "destination_id": address,
+        "sequence_id": payout_id,  # safe to retry: same ID returns the same transaction
+        "aml_cid": customer_id,
+        "memo": f"payout-{payout_id}",
+    }
+    if tag:
+        body["destination_tag"] = tag  # XRP / XLM
+    tx = finrock("POST", "/dac/v1/transaction", body)
+    db.update_payout(payout_id, finrock_id=tx["id"], status=tx["status"])
+    return tx
+
+
+def is_terminal(status: str) -> bool:
+    return status in TERMINAL
+```
+
+Prefer webhooks (`Withdraw` events carry your `sequence_id`) to update the payout status.
+If you must poll, back off from 5 s to 60 s and stop at a terminal status.

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@finrock/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "mcpName": "io.finrock/mcp",
+  "description": "MCP server that helps AI agents integrate Finrock crypto payments",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "start": "node dist/http.js",
+    "start:stdio": "node dist/stdio.js",
+    "dev": "tsx watch src/http.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gofinrock/mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "finrock",
+    "crypto",
+    "payments"
+  ],
+  "author": "Finrock",
+  "license": "SEE LICENSE IN LICENSE",
+  "bugs": {
+    "url": "https://github.com/gofinrock/mcp/issues"
+  },
+  "homepage": "https://github.com/gofinrock/mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "express": "^5.3.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.6.5",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  },
+  "type": "module",
+  "bin": {
+    "finrock-mcp": "dist/stdio.js"
+  },
+  "files": [
+    "dist",
+    "guides"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  }
+}