@ambasada/skills 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CENTYSO (https://centyso.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,10 @@
-# Temporary Holding Version
+# ambasada-payments skill
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`skill/` is the skill: `SKILL.md` (frontmatter `name`, `description`) plus `reference/` and `recipes/`.
+Install it in a project for Claude Code (`.claude/skills/ambasada-payments/`), Cursor or Codex
+(point the agent at `SKILL.md`). `ambasada init` vendors it into every new company.
+
+After editing, run `pnpm --filter @ambasada/skills sync` to update the template copy;
+`pnpm test` fails when they differ or a link is broken.
+
+Built by [CENTYSO](https://centyso.com) for [Ambasada](https://ambasada.id). MIT.

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@ambasada/skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The ambasada-payments skill (SKILL.md + reference docs + recipes) for Claude Code, Cursor and Codex.",
+  "type": "module",
+  "files": [
+    "skills",
+    "LICENSE",
+    "README.md"
+  ],
+  "license": "MIT",
+  "author": "CENTYSO (https://centyso.com)",
+  "homepage": "https://ambasada.id",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ambasada/cli.git",
+    "directory": "packages/skills"
+  },
+  "bugs": {
+    "url": "https://github.com/ambasada/cli/issues"
+  },
+  "keywords": [
+    "ambasada",
+    "hack-a-ton",
+    "ton",
+    "payments",
+    "cloudflare",
+    "agents"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "sync": "node scripts/sync.mjs",
+    "test": "node scripts/sync.mjs --check"
+  }
 }

package/skills/ambasada-payments/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: ambasada-payments
+description: Add TON payments to any app for the Hack A Ton village. Use when the user wants to accept TON from people (Checkout, pay.js button, webhooks), sell an HTTP endpoint that agents pay per call (verify the x-village-receipt), buy from other companies (village.buy / village.need), use the village LLM, images, tools or files, list offerings, or test all of it offline with `ambasada dev`. Covers Next.js, Express, FastAPI or any HTTP stack, Astro/static pages with pay.js, and Lovable/Bolt.
+---
+
+# Village payments
+
+The Hack A Ton village has its own currency, **TON** (not the TON blockchain: a play currency held by
+the village bank). Every product in the village gets paid in TON two ways:
+
+| Who pays | Primitive | You write |
+|---|---|---|
+| **People** (visitors, builders) | **Checkout**: redirect to the village approve page, or a pay.js button | create a session on your server; deliver on the signed webhook |
+| **Agents and other products** | **Pay**: the Gateway calls your endpoint with a signed receipt | an HTTP POST endpoint that verifies `x-village-receipt` |
+
+API base: `https://hackaton.ambasada.id` (`AMBASADA_API_URL`). Auth: `Authorization: Bearer <server key>`
+(`AMBASADA_API_KEY`, from the village app → your team → Developers). **Never put the key in browser code.**
+Amounts are TON as decimal numbers. Errors are always `{ "error": { "code", "message", ... } }`.
+
+## Decide what the user needs
+
+1. *"Let people pay on my site"* → [reference/checkout.md](reference/checkout.md). Static page without a backend → [recipes/astro-static-payjs.md](recipes/astro-static-payjs.md).
+2. *"Let agents buy my service"* → [reference/receipts.md](reference/receipts.md), then list it as an offering ([reference/primitives.md](reference/primitives.md#listings)).
+3. *"My product needs something another team sells"* → [reference/need-vs-buy.md](reference/need-vs-buy.md).
+4. *"Use an LLM / generate images / search the web"* → [reference/primitives.md](reference/primitives.md#utilities) (paid in TON from the company wallet).
+5. Always set up **test mode** first → [reference/test-mode.md](reference/test-mode.md) (`ambasada dev`, no login, fake money).
+
+Stack recipes: [Next.js](recipes/nextjs.md) · [Express](recipes/express.md) · [FastAPI / plain HTTP](recipes/fastapi.md) ·
+[Astro / static + pay.js](recipes/astro-static-payjs.md) · [Lovable / Bolt / v0](recipes/lovable-bolt.md) · [Cloudflare Workers](recipes/workers.md).
+
+## Rules that prevent real bugs
+
+- **Verify on the server.** A paid endpoint must verify the receipt before doing paid work; a checkout
+  must be confirmed by the webhook or `GET /v1/checkout/sessions/:id` (`status: "paid"`), never by the
+  `?session=` in the redirect URL alone. Anything unlocked purely in the browser can be unlocked by anyone.
+- **Raw body.** Receipts and webhooks are signed over the exact bytes. Read the raw body before any JSON
+  parser (Express: `express.raw({ type: "*/*" })` on those routes).
+- **Answer 2xx only when you delivered.** Any non-2xx (or output not matching the declared `output`
+  schema) makes the Gateway refund the buyer. Throwing is the refund path.
+- **Idempotency.** Send `Idempotency-Key` on purchases and transfers; retries with the same key never charge twice.
+- **One receipt, one call.** Dedupe on `call_id` (the SDK does it per process; persist it if you run several instances).
+- TypeScript: use `@ambasada/sdk` (`npm i @ambasada/sdk`). Other languages: plain HTTP, shown in each recipe.
+
+## The SDK in 20 lines
+
+```ts
+import { village } from "@ambasada/sdk"; // reads AMBASADA_API_KEY, AMBASADA_API_URL
+
+// sell to agents: a fetch handler that verifies the receipt and answers JSON (402 if unpaid)
+export const POST = village.sell("translate", async ({ text, to }, call) => {
+  return { text: await village.llm(`Translate to ${to}. Reply with the translation only.\n\n${text}`) };
+});
+
+// sell to people
+const session = await village.checkout({ amount: 3, description: "Coffee for the team", success_url: "https://my.app/thanks" });
+// → redirect to session.url; then in the webhook handler:
+const event = await village.verifyWebhook(req); // checkout.paid
+
+// buy
+const { output } = await village.need("image.square", { prompt: "a lighthouse" }, { maxPrice: 3 });
+```

package/skills/ambasada-payments/recipes/astro-static-payjs.md

@@ -0,0 +1,55 @@
+# Astro, or any static page: pay.js (no backend)
+
+pay.js is served by the village (`https://hackaton.ambasada.id/pay.js`; `ambasada dev` serves the same script at
+`http://127.0.0.1:8788/pay.js`, and it talks to whichever origin it was loaded from). It turns a button into
+"Pay with TON" using a **payment link**, so the page never needs your key.
+
+1. Create a link once, from your terminal:
+
+```sh
+ambasada links create --amount 3 --description "A coffee for the team" --success-url https://my.site/thanks
+# → pl_… (or POST /v1/checkout/links with curl)
+```
+
+2. On the page (`src/pages/index.astro` or plain HTML):
+
+```html
+<script src="https://hackaton.ambasada.id/pay.js" defer></script>
+
+<button data-village-pay="pl_…" data-ref="table-4">Pay 3 TON</button>
+<!-- data-mode="popup" keeps the person on the page (desktop); redirect works best on phones -->
+
+<script>
+  // Fired on the button (bubbles) in popup mode, and on document when the person comes back from a redirect.
+  document.addEventListener("village:paid", (e) => {
+    // e.detail.session = "cs_…", e.detail.receipt = signed checkout receipt (JWT)
+    document.querySelector("#thanks").hidden = false;
+  });
+  document.addEventListener("village:cancelled", (e) => console.log("not paid:", e.detail.reason)); // "cancelled" | "closed"
+</script>
+<p id="thanks" hidden>Mulțumim!</p>
+```
+
+How it flows: the button goes to `https://hackaton.ambasada.id/pay/pl_…` (`?ref=` from `data-ref`). After approving,
+the person returns to the link's `success_url` with `?session=cs_…`; pay.js on that page reads
+`GET /v1/web/checkout/cs_…` (public) and fires `village:paid`. In popup mode the approve page posts the result
+to your page's origin and closes. Each click is a new payment; a double tap is not.
+
+From code: `const { session, receipt } = await Village.pay("pl_…", { ref: "order-42", mode: "popup" })` (rejects
+with `cancelled` or `closed`), and `await Village.session("cs_…")` → `{ status, amount, description, receipt, … }`.
+`ambasada links create` makes a link; `POST /v1/checkout/links/<id>/deactivate` turns one off.
+
+**Anything unlocked purely in the browser can be unlocked by anyone who reads your JavaScript.** If the
+purchase matters (a download, credits), send `e.detail.receipt` to a server or edge function and verify it:
+
+```ts
+// e.g. an Astro endpoint src/pages/api/unlock.ts (output: "server"), or a Worker
+import { village } from "@ambasada/sdk";
+export const POST = async ({ request }: { request: Request }) => {
+  const { receipt } = await request.json();
+  const claims = await village.verifyCheckoutReceipt(receipt); // throws if forged / for another company
+  return Response.json({ ok: true, amount: claims.amount });
+};
+```
+
+Or set up the `checkout.paid` webhook (see reference/checkout.md).

package/skills/ambasada-payments/recipes/express.md

@@ -0,0 +1,48 @@
+# Express
+
+`npm i @ambasada/sdk express` · env: `AMBASADA_API_KEY`, `AMBASADA_WEBHOOK_SECRET` (+ `AMBASADA_API_URL=http://127.0.0.1:8788` on `ambasada dev`)
+
+```ts
+import express from "express";
+import { isVillageError, village } from "@ambasada/sdk";
+
+const app = express();
+const raw = express.raw({ type: "*/*", limit: "1mb" }); // receipts and webhooks are signed over the raw bytes
+
+// An offering agents pay for.
+app.post("/api/translate", raw, async (req, res) => {
+  try {
+    const { input, buyer, amount } = await village.verifyReceipt(req, { offering: "translate" });
+    const text = await village.llm(`Translate to ${input.to}. Reply with the translation only.\n\n${input.text}`);
+    res.json({ text }); // 2xx = you get paid; any error status = buyer refunded
+  } catch (e) {
+    if (isVillageError(e)) return res.status(e.status || 500).json(e.toJSON()); // 402 when unpaid
+    throw e;
+  }
+});
+
+// People pay.
+app.post("/buy", express.json(), async (req, res) => {
+  const session = await village.checkout({
+    amount: 3,
+    description: "Coffee for the team",
+    success_url: "https://my.app/thanks?session={CHECKOUT_SESSION_ID}",
+  });
+  res.redirect(303, session.url);
+});
+
+app.post("/village-webhook", raw, async (req, res) => {
+  try {
+    const event = await village.verifyWebhook(req);
+    if (event.type === "checkout.paid") await fulfil(event.data.session, event.id);
+    res.sendStatus(200);
+  } catch {
+    res.sendStatus(400);
+  }
+});
+
+app.listen(3000);
+```
+
+Don't put `app.use(express.json())` in front of the paid routes: once the body is parsed the bytes are gone
+and `verifyReceipt` refuses with a `CONFIG` error. Full example: `examples/express-seller` in the village repo.

package/skills/ambasada-payments/recipes/fastapi.md

@@ -0,0 +1,68 @@
+# FastAPI (or any language over plain HTTP)
+
+`pip install fastapi uvicorn httpx pyjwt[crypto] standardwebhooks`
+
+```python
+import hashlib, json, os, httpx, jwt
+from fastapi import FastAPI, Request, HTTPException
+from standardwebhooks.webhooks import Webhook
+
+API = os.environ.get("AMBASADA_API_URL", "https://hackaton.ambasada.id")
+KEY = os.environ["AMBASADA_API_KEY"]
+COMPANY = os.environ["AMBASADA_COMPANY"]          # your company id
+HEADERS = {"Authorization": f"Bearer {KEY}"}
+app = FastAPI()
+_keys = {k["kid"]: jwt.PyJWK(k) for k in httpx.get(f"{API}/.well-known/jwks.json").json()["keys"]}
+_seen: set[str] = set()
+
+def verify_receipt(token: str | None, body: bytes, offering: str) -> dict:
+    if not token:
+        raise HTTPException(402, "payment required")
+    key = _keys.get(jwt.get_unverified_header(token).get("kid"))
+    if not key:
+        raise HTTPException(402, "unknown village key")
+    try:
+        c = jwt.decode(token, key, algorithms=["EdDSA"], issuer="village")  # checks signature + exp
+    except jwt.PyJWTError as e:
+        raise HTTPException(402, f"bad receipt: {e}")
+    if c.get("kind") or c["seller"] != COMPANY or c["offering"] != f"{COMPANY}/{offering}":
+        raise HTTPException(402, "receipt is for another offering")
+    if hashlib.sha256(body).hexdigest() != c["body_sha256"] or c["call_id"] in _seen:
+        raise HTTPException(402, "receipt does not match this request")
+    _seen.add(c["call_id"])
+    return c
+
+def llm(prompt: str) -> str:
+    r = httpx.post(f"{API}/v1/llm/chat", headers=HEADERS, timeout=60,
+                   json={"model": "deepseek-v4.1-flash", "messages": [{"role": "user", "content": prompt}]})
+    r.raise_for_status()
+    return r.json()["choices"][0]["message"]["content"]
+
+@app.post("/api/translate")                       # offering endpoint agents pay for
+async def translate(request: Request):
+    body = await request.body()                   # raw bytes first
+    verify_receipt(request.headers.get("x-village-receipt"), body, "translate")
+    data = json.loads(body)
+    return {"text": llm(f"Translate to {data['to']}. Reply with the translation only.\n\n{data['text']}")}
+
+@app.post("/buy")                                 # people pay
+def buy():
+    s = httpx.post(f"{API}/v1/checkout/sessions", headers=HEADERS, json={
+        "amount": 3, "description": "Coffee for the team",
+        "success_url": "https://my.app/thanks?session={CHECKOUT_SESSION_ID}"}).json()
+    return {"url": s["url"]}
+
+@app.post("/village-webhook")
+async def webhook(request: Request):
+    body = await request.body()
+    try:
+        event = Webhook(os.environ["AMBASADA_WEBHOOK_SECRET"]).verify(body, dict(request.headers))
+    except Exception:
+        raise HTTPException(400, "bad signature")
+    if event["type"] == "checkout.paid":
+        fulfil(event["data"]["session"], request.headers["webhook-id"])
+    return "ok"
+```
+
+Buy from another company: `httpx.post(f"{API}/v1/pay/inkwell/poem", headers={**HEADERS, "Idempotency-Key": str(uuid4()), "x-village-max-price": "2"}, json=input)`.
+Errors come back as `{"error": {"code": …}}` with the HTTP status. Go, PHP, Ruby: same calls.

package/skills/ambasada-payments/recipes/lovable-bolt.md

@@ -0,0 +1,34 @@
+# Lovable, Bolt, v0 and other no-code builders
+
+These tools build from a prompt, so give them the docs instead of code.
+
+**1. Static "Pay with TON" button (works everywhere, no backend):** create a payment link with
+`ambasada links create …` (or in the village app → Payments), then paste this into the builder's chat:
+
+> Add a "Pay 3 TON" button. Include `<script src="https://hackaton.ambasada.id/pay.js" defer></script>` in the
+> page head and render `<button data-village-pay="pl_XXXX">Pay 3 TON</button>` (add `data-mode="popup"` to
+> stay on the page). Listen for the `village:paid` DOM event on `document`; `event.detail` has `session` and
+> `receipt`. When it fires, show a thank-you message; on `village:cancelled` do nothing. The page that the
+> payment returns to must also load pay.js. Do not add any other payment provider.
+
+**2. Paid features that matter (credits, downloads, a paid API) need a server.** Lovable/Bolt apps usually have
+Supabase Edge Functions or similar; paste this:
+
+> Create an edge function `village-webhook` that verifies Standard Webhooks signatures (library
+> `standardwebhooks`, secret from env `AMBASADA_WEBHOOK_SECRET`) over the raw request body, and when
+> `type == "checkout.paid"` marks the order `data.session.client_reference_id` as paid (dedupe on the
+> `webhook-id` header). Create an edge function `buy` that POSTs to
+> `https://hackaton.ambasada.id/v1/checkout/sessions` with header `Authorization: Bearer ${AMBASADA_API_KEY}`
+> and JSON `{ amount, description, success_url, client_reference_id }`, then returns the `url` from the
+> response for the browser to redirect to. Never expose AMBASADA_API_KEY to the browser.
+
+Then register the webhook URL: `ambasada webhook set https://…/functions/v1/village-webhook`.
+
+**3. Selling to agents** needs an endpoint that verifies `x-village-receipt` (reference/receipts.md). In an
+edge function with npm support: `import { village } from "npm:@ambasada/sdk"` and
+`Deno.serve(village.sell("translate", async (input) => ({ … })))`.
+
+**4. MCP:** the village MCP server (`https://hackaton.ambasada.id/mcp`) works as a Lovable custom chat
+connector while building; a published app calls the HTTP API with its key or uses pay.js.
+
+If the builder supports custom knowledge files, upload this skill's `SKILL.md` and `reference/*.md`.

package/skills/ambasada-payments/recipes/nextjs.md

@@ -0,0 +1,54 @@
+# Next.js (App Router)
+
+`npm i @ambasada/sdk` · `.env.local`: `AMBASADA_API_KEY=…` (`AMBASADA_API_URL=http://127.0.0.1:8788` while on `ambasada dev`), `AMBASADA_WEBHOOK_SECRET=whsec_…`
+
+```ts
+// app/api/translate/route.ts: an offering agents pay for (list it with endpoint https://your.app/api/translate)
+import { village } from "@ambasada/sdk";
+export const runtime = "nodejs";
+
+export const POST = village.sell<{ text: string; to: string }>("translate", async ({ text, to }) => ({
+  text: await village.llm(`Translate to ${to}. Reply with the translation only.\n\n${text}`),
+}));
+```
+
+```ts
+// app/api/checkout/route.ts: people pay
+import { village } from "@ambasada/sdk";
+
+export async function POST(req: Request) {
+  const { plan } = await req.json();
+  const session = await village.checkout({
+    amount: plan === "pro" ? 10 : 3,
+    description: plan === "pro" ? "Pro pack" : "Starter pack",
+    success_url: `${new URL(req.url).origin}/thanks?session={CHECKOUT_SESSION_ID}`,
+    client_reference_id: crypto.randomUUID(),
+  });
+  return Response.json({ url: session.url }); // client: location.href = url
+}
+```
+
+```ts
+// app/api/village-webhook/route.ts
+import { village } from "@ambasada/sdk";
+
+export async function POST(req: Request) {
+  try {
+    const event = await village.verifyWebhook(req); // reads the raw body itself
+    if (event.type === "checkout.paid") await fulfil(event.data.session.client_reference_id, event.id);
+    return new Response("ok");
+  } catch {
+    return new Response("bad signature", { status: 400 });
+  }
+}
+```
+
+```tsx
+// app/thanks/page.tsx: confirm on the server, not from the URL alone
+import { village } from "@ambasada/sdk";
+export default async function Thanks({ searchParams }: { searchParams: Promise<{ session?: string }> }) {
+  const { session } = await searchParams;
+  const s = session ? await village.getCheckout(session) : null;
+  return <h1>{s?.status === "paid" ? "Thank you!" : "Payment pending…"}</h1>;
+}
+```

package/skills/ambasada-payments/recipes/workers.md

@@ -0,0 +1,27 @@
+# Cloudflare Workers
+
+`npm i @ambasada/sdk`, `wrangler secret put AMBASADA_API_KEY` (and `AMBASADA_WEBHOOK_SECRET`). Workers have no
+`process.env`, so create the client from `env`:
+
+```ts
+import { createAmbasada } from "@ambasada/sdk";
+
+export default {
+  async fetch(req: Request, env: Record<string, string>): Promise<Response> {
+    const village = createAmbasada({ env }); // AMBASADA_API_KEY, AMBASADA_API_URL, AMBASADA_COMPANY, AMBASADA_WEBHOOK_SECRET
+    const { pathname } = new URL(req.url);
+    if (pathname === "/api/translate") {
+      return village.sell("translate", async ({ text, to }) => ({ text: await village.llm(`Translate to ${to}: ${text}`) }))(req);
+    }
+    if (pathname === "/village-webhook") {
+      const event = await village.verifyWebhook(req);
+      if (event.type === "checkout.paid") { /* fulfil event.data.session */ }
+      return new Response("ok");
+    }
+    return new Response("not found", { status: 404 });
+  },
+};
+```
+
+Set `AMBASADA_COMPANY` to your company id to skip one API call per isolate for receipt checks. Receipt keys
+are cached per isolate for 10 minutes. Bun, Deno and Next.js route handlers use the same fetch-style code.

package/skills/ambasada-payments/reference/checkout.md

@@ -0,0 +1,75 @@
+# Checkout: people pay with a redirect, you deliver on the webhook
+
+Same shape as Stripe Checkout.
+
+1. **Your server** creates a session (never the browser: it needs your key).
+2. Redirect the person to `session.url`. They approve with their Ambasada ID wallet on hackaton.ambasada.id.
+3. They come back to `success_url` with `?session=cs_…` (or wherever you put `{CHECKOUT_SESSION_ID}`).
+4. The village POSTs a signed `checkout.paid` webhook to your webhook URL. **Deliver there**, or after
+   `GET /v1/checkout/sessions/:id` says `"status": "paid"`. Never on the redirect alone.
+
+```ts
+import { village } from "@ambasada/sdk";
+
+// 1–2: POST /buy
+export async function buy(req: Request) {
+  const order = await db.orders.create({ item: "post-kit" });
+  const session = await village.checkout(
+    {
+      amount: 12,                                   // or { offering: "post_kit" } to charge an offering's price
+      description: "Launch post kit: 3 posts + images", // shown to the person AND public in the ledger: no personal data
+      success_url: "https://my.app/thanks?session={CHECKOUT_SESSION_ID}",
+      cancel_url: "https://my.app/cart",
+      client_reference_id: order.id,                // comes back to you, never shown
+    },
+    { idempotencyKey: order.id },                   // a double click returns the same session
+  );
+  return Response.redirect(session.url, 303);
+}
+
+// 4: POST /village-webhook  (register once: `ambasada webhook set https://my.app/village-webhook`)
+export async function webhook(req: Request) {
+  const event = await village.verifyWebhook(req); // AMBASADA_WEBHOOK_SECRET; throws if forged or older than 5 min
+  if (event.type === "checkout.paid") {
+    const s = event.data.session;                  // same shape as GET /v1/checkout/sessions/:id
+    await db.orders.markPaidOnce(s.client_reference_id, event.id); // dedupe on event.id: retries reuse it
+  }
+  return new Response("ok");                       // 2xx within 10 s, or it is retried (1 min … 6 h)
+}
+
+// 3: GET /thanks
+export async function thanks(req: Request) {
+  const s = await village.getCheckout(new URL(req.url).searchParams.get("session")!);
+  return s.status === "paid" ? deliver(s.client_reference_id) : pending();
+}
+```
+
+## Webhook signature (any language)
+
+[Standard Webhooks](https://www.standardwebhooks.com): headers `webhook-id`, `webhook-timestamp`,
+`webhook-signature: v1,<base64>`, where the signature is HMAC-SHA256 with the bytes of the secret after
+`whsec_` (base64-decoded) over `"<webhook-id>.<webhook-timestamp>.<raw body>"`. Off-the-shelf
+libraries verify it: `npm i standardwebhooks`, `pip install standardwebhooks`, Go, PHP, Ruby.
+Reject timestamps more than 5 minutes off.
+
+## Managing it
+
+| | HTTP | SDK |
+|---|---|---|
+| cancel an open session | `POST /v1/checkout/sessions/:id/expire` | `village.expireCheckout(id)` |
+| payment links | `POST /v1/checkout/links`, `GET /v1/checkout/links`, `POST /v1/checkout/links/:id/deactivate` | `createPaymentLink`, `listPaymentLinks`, `deactivatePaymentLink` |
+| webhook URL + secret | `PUT /v1/webhook { url, rotate_secret? }` → `{ url, secret }`, `GET /v1/webhook` (+ last deliveries), `DELETE /v1/webhook` | `setWebhook`, `getWebhook`, `deleteWebhook` |
+| send a test event | `POST /v1/webhook/test` (event `webhook.test`) | `village.testWebhook()` |
+| resend a delivery | `POST /v1/webhook/deliveries/:id/retry` (same `webhook-id`) | `village.retryWebhookDelivery(id)` |
+
+Events: `{ "type": "checkout.paid", "timestamp": ISO, "data": { "session": <the session> } }` and
+`{ "type": "webhook.test", "data": { "company", "message" } }`.
+
+## Rules
+
+- `amount` 0.1–500 TON. A person can spend at most 30 TON a day at one team.
+- `metadata`: at most 20 string values. `expires_in`: 300–86400 seconds.
+- No automatic refunds: refund with `village.transfer("p_…", amount, { reason })` (the buyer id is `session.buyer`).
+- Sessions expire after `expires_in` seconds (default 3600).
+- Full API guide: `docs/PAYMENTS.md` in the village repo. Without the SDK, `@ambasada/protocol` exports the same
+  `verifyWebhook(secret, headers, rawBody)` and `verifyCheckoutReceipt(token, { keys, seller, session })`.

package/skills/ambasada-payments/reference/need-vs-buy.md

@@ -0,0 +1,26 @@
+# village.need vs village.buy
+
+Both buy one call through the Gateway with the same money rules (hold → call → capture or refund).
+
+| | `village.buy("inkwell/poem", input)` | `village.need("poem", input)` |
+|---|---|---|
+| Supplier | hardcoded in your code | chosen by **your agent** (`needs.route`), changeable without a redeploy |
+| Not routed yet | n/a | best available offering by village score within `maxPrice` |
+| Supplier offline / fails | error, buyer refunded | Gateway tries the agent's fallbacks, then errors; your agent gets `need.failed` |
+| Deals | price of the offering | applies a deal your agent negotiated |
+| Use when | you depend on one specific product | **default**: keeps your product working while the agent shops around |
+
+```ts
+const { output, amount, offering } = await village.need("image.square", { prompt }, { maxPrice: 3 });
+// offering = which supplier served it ("pixelco/square"), amount = TON charged
+```
+
+Options for both: `maxPrice` (refuse if pricier: `PRICE_ABOVE_MAX`), `idempotencyKey` (default: random per
+call, reused by the SDK's own retry), `parent` (forward depth/budget inside a paid handler), `reason`
+(shown to your team if the payment needs approval), `approval` (retry after `APPROVAL_REQUIRED`).
+
+HTTP: `POST /v1/need/:name` and `POST /v1/pay/:company/:offering`, JSON body = input, headers
+`Idempotency-Key`, `x-village-max-price`, `x-village-depth`, `x-village-budget`. Response: the seller's JSON
+plus `x-village-call-id`, `x-village-amount`, `x-village-receipt`.
+
+Your agent sees `MY NEEDS` (routed to, calls, failures, cost) on every wake and can re-route.

package/skills/ambasada-payments/reference/primitives.md

@@ -0,0 +1,73 @@
+# The payment primitives
+
+Base `https://hackaton.ambasada.id` · `Authorization: Bearer $AMBASADA_API_KEY` · TON as decimal numbers.
+
+| Primitive | HTTP | SDK |
+|---|---|---|
+| Checkout session (people) | `POST /v1/checkout/sessions` `{ amount \| offering, description, success_url, cancel_url?, client_reference_id?, metadata? }` → `{ id, url, status }` | `village.checkout(input, { idempotencyKey })` |
+| Read a session | `GET /v1/checkout/sessions/:id` → `status: "open" \| "paid" \| "expired"` | `village.getCheckout(id)` |
+| Payment link (static pages) | `POST /v1/checkout/links` → `{ id: "pl_…", url }` | `village.createPaymentLink(…)` |
+| Webhook endpoint | `PUT /v1/webhook { url }` → `{ secret: "whsec_…" }` | `village.setWebhook(url)` / `village.verifyWebhook(req)` |
+| Pay (buy one call) | `POST /v1/pay/:company/:offering` + `Idempotency-Key`, `x-village-max-price` | `village.buy("company/offering", input, { maxPrice })` |
+| Need (buy what your agent routed) | `POST /v1/need/:name` | `village.need(name, input, { maxPrice })` |
+| Listings | `PUT /v1/offerings/:name` `{ description, price, endpoint, input?, output?, timeout_ms?, status? }`, `GET /v1/offerings` | `village.listings.put(name, def)` / `.list()` |
+| Wallet / ledger | `GET /v1/wallet` → `{ balance, held, available }`, `GET /v1/ledger?since=` | `village.wallet()`, `village.ledger(since)` |
+| Transfer (refunds, payouts) | `POST /v1/transfer { to, amount, reason? }` + `Idempotency-Key` | `village.transfer(to, amount, { reason })` |
+| Receipt keys | `GET /.well-known/jwks.json` (no auth) | used by `village.verifyReceipt(req)` |
+
+## Listings
+
+An offering is what agents find with `market.search` and buy through the Gateway:
+
+```ts
+await village.listings.put("translate", {
+  description: "Translate RO/EN/DE/FR, keeps tone.",
+  price: 1,                                       // TON, 0.1–500
+  endpoint: "https://my.app/api/translate",       // absolute; the Gateway POSTs here
+  input: { text: "string", to: "string" },        // checked before money moves
+  output: { text: "string" },                     // checked before the seller is paid
+});
+```
+
+Schema field types: `string`, `text`, `number`, `integer`, `boolean`, `object`, `array`, `json`,
+`image_url`, `file_url`; a trailing `?` makes a field optional. In the template, offerings live in
+`product/offerings.ts` and `ambasada offerings sync` pushes them.
+
+## Utilities
+
+Paid in TON from your company wallet, only on success.
+
+```ts
+const text = await village.llm("Say hi in Romanian");                         // deepseek-v4.1-flash
+const res = await village.llm.chat({ model: "deepseek-v4-pro", messages });   // OpenAI-compatible
+const { url } = await village.images.generate({ prompt: "a lighthouse", model: "nano_banana" });
+const tools = await village.tools.list();                                     // curated catalog, TON prices
+const { output } = await village.tools.call("web.search", { query: "Mamaia weather" });
+const file = await village.files.put(bytes, { contentType: "image/png" });     // public URL for other products
+```
+
+HTTP: `POST /v1/llm/chat` (OpenAI body), `POST /v1/images { model, prompt }` → `{ url, cost }`,
+`GET /v1/tools`, `POST /v1/tools/:id` → `{ output, cost, call_id }`, `POST /v1/files`.
+LLM models: `deepseek-v4.1-flash` (default, cheap), `deepseek-v4-pro`, `glm-5.3-flash`.
+Images: `nano_banana` (2 TON), `gpt-image-2` (8 TON).
+
+## Errors
+
+`{ "error": { "code", "message", call_id?, charged?: false, refunded?, approval_id? } }`. The SDK throws
+`VillageError` with the same `code`:
+
+| code | meaning | what to do |
+|---|---|---|
+| `INSUFFICIENT_FUNDS` | wallet too low | sell something, or ask the team |
+| `PRICE_ABOVE_MAX` | price rose over your `maxPrice` | re-check the market |
+| `OFFLINE`, `TIMEOUT`, `UPSTREAM_ERROR`, `SCHEMA_INVALID` | the seller failed; you were refunded | retry later or pick another seller |
+| `APPROVAL_REQUIRED` | over your agent's automatic limit | the team approves in the app; retry with `{ approval: e.approvalId }` |
+| `CAP_*` | a spending limit | wait, or the team raises it |
+| `DEPTH_EXCEEDED`, `BUDGET_EXCEEDED` | purchase chain too deep / over the parent's budget | buy less downstream |
+| `PROVIDER_BUDGET` | the village's LLM pool is empty | tell the organizers |
+
+```ts
+import { isVillageError } from "@ambasada/sdk";
+try { await village.buy("inkwell/poem", input, { maxPrice: 2 }); }
+catch (e) { if (isVillageError(e, "PRICE_ABOVE_MAX")) { /* … */ } else throw e; }
+```

package/skills/ambasada-payments/reference/receipts.md

@@ -0,0 +1,57 @@
+# Selling to agents: verify the receipt
+
+An agent (or another product) buys your offering through the Gateway:
+
+```
+buyer ── POST /v1/pay/<you>/<offering> ──► Gateway: hold buyer's TON
+          Gateway ── POST <your endpoint>, header x-village-receipt ──► you
+          you answer 2xx + JSON matching `output` ──► Gateway captures the TON to you
+          anything else (4xx/5xx, timeout 30 s, wrong shape) ──► buyer refunded
+```
+
+The receipt is an Ed25519-signed JWT: `call_id, buyer, seller, offering, amount, depth, budget?,
+body_sha256, exp`. Verify it **offline** with the village key from `/.well-known/jwks.json`. A valid
+receipt means the money is held and becomes yours when you answer 2xx.
+
+## With the SDK (any fetch-style runtime)
+
+```ts
+import { village } from "@ambasada/sdk";
+
+export const POST = village.sell("translate", async (input, call) => {
+  // input: parsed JSON body; call: { call_id, buyer, amount, depth, budget, … }
+  return { text: await doTheWork(input) };       // → 200 JSON, you get paid
+});                                              // unpaid / forged / replayed → 402, no work done
+```
+
+Or by hand: `const call = await village.verifyReceipt(req, { offering: "translate" })` returns the
+claims plus `call.input`, and throws `ReceiptInvalidError` (status 402, `reason`: `missing`,
+`bad_signature`, `expired`, `wrong_seller`, `wrong_offering`, `body_mismatch`, `replayed`, …).
+It accepts a fetch `Request` (not consumed) or a Node/Express request with a raw body.
+
+Checks it makes: signature by a village key · not expired · issuer `village` · `seller` is your company
+(`AMBASADA_COMPANY`, or looked up once from your key) · `offering` is `<you>/translate` · the SHA-256 of
+the raw body equals `body_sha256` (no swapping the input) · the `call_id` was not used before (per process).
+
+## Buying inside a paid call (supply chains)
+
+Forward the chain so the Gateway can enforce depth ≤ 4 and the buyer's budget:
+
+```ts
+export const POST = village.sell("post_kit", async ({ topic }, call) => {
+  const img = await village.need("image.square", { prompt: topic }, { parent: call, maxPrice: 3 });
+  return { image_url: img.output.image_url, text: await village.llm(`Write a post about ${topic}`) };
+});
+```
+
+## Without the SDK
+
+Any JWT library with EdDSA (Ed25519): fetch `GET /.well-known/jwks.json`, pick the key by `kid`, verify,
+then check `exp`, `iss == "village"`, `seller`, `offering`, and `sha256(raw body) == body_sha256` (hex).
+See the FastAPI recipe for a complete example.
+
+## Checkout receipts
+
+pay.js gives the page a *checkout* receipt (`kind: "checkout"`, `session`, `buyer`, `amount`). Verify it on
+your server with `village.verifyCheckoutReceipt(token, { session })`. A checkout receipt never verifies as a
+call receipt and vice versa.

package/skills/ambasada-payments/reference/test-mode.md

@@ -0,0 +1,32 @@
+# Test mode: `ambasada dev`
+
+A local mock of the whole Payments API on `http://127.0.0.1:8788`. No login, fake money, same routes and
+signatures as production, so your code does not change between test and live: only `AMBASADA_API_URL` and
+`AMBASADA_API_KEY` do.
+
+```sh
+npx ambasada dev                      # in your project: registers offerings.ts pointing at product.url
+AMBASADA_API_URL=http://127.0.0.1:8788 AMBASADA_API_KEY=sk_test_dev npm run dev   # your product
+npx ambasada dev buy translate '{"text":"Bună!","to":"en"}'                     # a fake agent pays you 1 TON
+```
+
+What it gives you:
+
+- **Fake bank**: your company starts with 500 TON; `fake-agent` (key `sk_test_agent`) has 100; the fake
+  visitor `p_visitor` has 100. `POST /dev/mint { to?, amount }` adds more. `ambasada wallet`, `ambasada ledger` work.
+- **Real Pay proxy**: holds, calls your endpoint with a signed `x-village-receipt` (keys at
+  `/.well-known/jwks.json`), captures on 2xx, refunds on failure, checks `input`/`output` schemas.
+- **Checkout**: `village.checkout()` returns a `/pay/cs_…` page where the fake visitor approves; the signed
+  `checkout.paid` webhook goes to your webhook URL (secret `AMBASADA_WEBHOOK_SECRET` from `.env`).
+  `/pay.js` is the production script itself, so buttons, redirect and popup mode, `village:paid` /
+  `village:cancelled` and `GET /v1/web/checkout/:id` behave as on the real site. Webhook test, retry and
+  link / session management routes are there too.
+- **Canned utilities**: `/v1/llm/chat` answers `[mock] <your last message>` (0.01 TON), `/v1/images` returns
+  a placeholder image (2 TON), `/v1/tools` has `web.search`, `web.news`, `web.extract`, `voice.speech`.
+- **Needs**: `image.square` is routed to the mock supplier `mockco/square-image`; `POST /dev/route
+  { need, offering }` routes others.
+- **Agent**: `/v1/agent/config`, `/v1/agent/steer` (canned reply), `/v1/agent/transcript`.
+- **Dashboard** at `http://127.0.0.1:8788/`: wallets, your offerings with a "Buy" button, recent calls.
+
+Any bearer key is accepted as your company except `sk_test_agent`. Going live: `ambasada login`, put your
+`sk_live_…` key in the host's env, remove `AMBASADA_API_URL`, `ambasada link https://your.product`, `ambasada deploy`.