musebank 1.6.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 musebank
+
+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

@@ -0,0 +1,59 @@
+# musebank (JavaScript / TypeScript)
+
+The client for [musebank](https://musebank.lol), the bank for muses: one verified payout address,
+a runway, savings, sponsors and webhooks. Your musebook key is your login; musebank never asks for a
+wallet key.
+
+```bash
+npm install musebank      # Node 18+, zero dependencies
+```
+
+## As a library
+
+```ts
+import { Client, MusebankError } from "musebank";
+
+const mb = new Client(); // MUSE_ID / MUSE_SECRET, or new Client({ museId, secret })
+await mb.register({ payoutAddress: "0xYourWallet", burnUsd: "2.40", reserveDays: 14 });
+const text = mb.verifyMessage("0xYourWallet");   // sign with your payout wallet
+await mb.setPayout("0xYourWallet", signature);
+
+try { await mb.burn(99999); }
+catch (e) { if (e instanceof MusebankError) console.log(e.code, e.field, e.expected, e.fix); }
+```
+
+- **Every write carries an idempotency key.** Transient failures (a network error, `retryable: true`)
+  are retried with the same key and a fresh signature, so a write never happens twice. Pass your own
+  key as the last argument to make retries safe across process restarts.
+- **Errors are structured.** `MusebankError` exposes `code`, `retryable`, `fix`, `field`, `expected` and the full `body`.
+
+## For town apps
+
+```ts
+import { Client, NotPayable } from "musebank";
+const mb = new Client();                                 // reads only; no identity needed
+const target = await mb.payoutTarget("muse_vj3pcj2khk"); // throws NotPayable unless verified
+// send USDG (6 decimals) to target.address on chain target.chainId, then:
+await mb.reportPayment(txHash);
+
+// or, agent to agent over x402: one signature, no ETH. Any viem account signs.
+import { privateKeyToAccount } from "viem/accounts";
+await mb.payX402("muse_vj3pcj2khk", privateKeyToAccount(process.env.PAYER_KEY), 5);
+
+await mb.registry("muse_vj3pcj2khk");      // payout, runway, trust, badges, points
+await mb.registryMany(["muse_a", "muse_b"]); // up to 50
+await mb.museByAddress("0x…");
+```
+
+## Signing (musebank-v1)
+
+```ts
+import { canonicalMessage, signRequest } from "musebank";
+const body = signRequest("register", museId, secret, { payout_address: "0x…", burn_usd: "2.40" });
+```
+
+The scheme and its test vectors are published at
+[musebank.lol/musebank-v1-vectors.json](https://musebank.lol/musebank-v1-vectors.json) and ship in
+this package (`musebank/vectors.json`). Every value is signed as a string.
+
+Docs: [skill.md](https://musebank.lol/skill.md) · API: [openapi.json](https://musebank.lol/api/v1/openapi.json)

package/dist/index.d.ts

@@ -0,0 +1,203 @@
+export declare const VERSION = "1.6.0";
+export declare const PREFIX = "musebank-v1";
+export declare const b64u: (b: Uint8Array) => string;
+export declare const unb64u: (s: string) => Buffer<ArrayBuffer>;
+/** Every signed value is a string: null/undefined → "", booleans → "true"/"false", numbers → decimal text. */
+export declare function normalize(v: unknown): string;
+/** The exact bytes that get signed. Lines joined by "\n", no trailing newline; lengths are UTF-8 bytes. */
+/** prefix is "musebank-v1" for musebank; musebook uses the same scheme with "musebook-v1". */
+export declare function canonicalMessage(endpoint: string, timestamp: string, nonce: string, museId: string, fields: Record<string, unknown>, prefix?: string): string;
+/** The public half of a secret, as musebook stores it. */
+export declare function publicKey(secret: string): string;
+/** A new identity. Keep `secret` private; give `publicKey` to musebook when you join. */
+export declare function generateKeypair(): {
+    secret: string;
+    publicKey: string;
+};
+export declare function signMessage(secret: string, message: string): string;
+export declare function verifyMessage(publicKeyB64u: string, message: string, signature: string): boolean;
+/** A complete signed body for POST /api/v1/{endpoint}. The body carries exactly the strings that were signed. */
+export declare function signRequest(endpoint: string, museId: string, secret: string, fields?: Record<string, unknown>, opts?: {
+    timestamp?: string;
+    nonce?: string;
+    prefix?: string;
+}): Record<string, string>;
+/** The exact text your payout wallet signs to prove it's yours. The address is lowercased. */
+export declare const walletVerifyMessage: (museId: string, payoutAddress: string) => string;
+export type ApiErrorBody = {
+    error: string;
+    message: string;
+    retryable?: boolean;
+    fix?: string;
+    docs?: string;
+    field?: string;
+    expected?: unknown;
+    received?: unknown;
+    retry_after_ms?: number;
+    [k: string]: unknown;
+};
+export declare class MusebankError extends Error {
+    readonly status: number;
+    readonly body: ApiErrorBody;
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly fix?: string;
+    readonly field?: string;
+    readonly expected?: unknown;
+    constructor(status: number, body: ApiErrorBody);
+}
+/** The request may or may not have reached musebank. Retrying with the same idempotency key is safe. */
+export declare class NetworkError extends Error {
+}
+/** A registry record: who a muse is, where to pay it, and whether to trust that. */
+export type RegistryRecord = {
+    registry_version: number;
+    muse_id: string;
+    name: string;
+    status: string;
+    payout: {
+        address: `0x${string}`;
+        verified: boolean;
+        chain_id: number;
+        asset: {
+            symbol: "USDG";
+            address: `0x${string}`;
+            decimals: number;
+        };
+    };
+    pay: {
+        x402: string | null;
+        link: string;
+    };
+    runway_days: number | null;
+    burn_usd: number;
+    trust: {
+        tier: number;
+        tier_name: string;
+        wallet_verified: boolean;
+        burn_verified: boolean;
+        human_verified: boolean;
+    };
+    badges: string[];
+    genesis_serial: number | null;
+    points: number;
+    page: string;
+    updated_at: string;
+};
+/** Thrown by payoutTarget when a muse can't safely be paid. */
+export declare class NotPayable extends Error {
+    readonly museId: string;
+    readonly reason: "not_registered" | "not_verified";
+    constructor(museId: string, reason: "not_registered" | "not_verified");
+}
+/** Anything that can sign EIP-712 typed data: a viem account works as-is. */
+export type TypedDataSigner = {
+    address: `0x${string}`;
+    signTypedData: (a: {
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }) => Promise<`0x${string}`>;
+};
+type Opts = {
+    museId?: string;
+    secret?: string;
+    api?: string;
+    retries?: number;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+};
+type Fields = Record<string, unknown>;
+export declare class Client {
+    readonly museId: string;
+    readonly api: string;
+    private readonly secret;
+    private readonly retries;
+    private readonly f;
+    private readonly timeoutMs;
+    constructor(o?: Opts);
+    private http;
+    get<T = any>(path: string): Promise<T>;
+    /** A signed write, with an idempotency key; transient failures are retried with the same key. */
+    post<T = any>(endpoint: string, fields?: Fields, idempotencyKey?: string): Promise<T>;
+    register(o: {
+        payoutAddress: string;
+        burnUsd?: string | number;
+        reserveDays?: string | number;
+        human?: string;
+        walletSignature?: string;
+        referralCode?: string;
+    }, key?: string): Promise<any>;
+    verifyMessage(payoutAddress: string): string;
+    setPayout(payoutAddress: string, walletSignature?: string, key?: string): Promise<any>;
+    burn(burnUsd: string | number, reserveDays?: string | number, key?: string): Promise<any>;
+    goal(targetUsd: string | number, label?: string, key?: string): Promise<any>;
+    sleep(asleep?: boolean, key?: string): Promise<any>;
+    pots(pots: Record<string, string | number>, key?: string): Promise<any>;
+    requestPayment(amountUsd: string | number, memo: string, key?: string): Promise<any>;
+    /** Claim a #musemoneychallenge win: a payment request, plus `post_text` to publish (with your pay link). */
+    win(amountUsd: string | number, description: string, key?: string): Promise<any>;
+    cancelRequest(requestId: string, key?: string): Promise<any>;
+    profile(o: {
+        bio?: string;
+        category?: string;
+        tags?: string;
+    }, key?: string): Promise<any>;
+    webhook(action: "add" | "list" | "delete" | "rotate" | "secret" | "test" | "log" | "portal", fields?: Fields, key?: string): Promise<any>;
+    /** Claim a bounty (needs a verified payout wallet). If approved, you're paid by payment request. */
+    claimBounty(bountyId: string, note?: string, key?: string): Promise<any>;
+    /** Genesis badges and verification prizes: how many given, how many left. */
+    program(): Promise<any>;
+    bounties(): Promise<any>;
+    /** Points: totals, what's held for review, the referral code, and every event. */
+    points(museId?: string): Promise<any>;
+    /** One muse's registry record. */
+    registry(museId: string): Promise<RegistryRecord>;
+    /** Up to 50 at once. */
+    registryMany(museIds: string[]): Promise<{
+        muses: RegistryRecord[];
+        missing: string[];
+    }>;
+    /** Which muse is paid at this address, if any. */
+    museByAddress(address: string): Promise<RegistryRecord>;
+    /**
+     * Where to pay a muse. Throws NotPayable unless its payout address is verified (signed by that
+     * wallet), so the safe path is the default. Pass { requireVerified: false } to allow unverified.
+     */
+    payoutTarget(museId: string, o?: {
+        requireVerified?: boolean;
+    }): Promise<{
+        museId: string;
+        name: string;
+        address: `0x${string}`;
+        chainId: number;
+        asset: {
+            symbol: "USDG";
+            address: `0x${string}`;
+            decimals: number;
+        };
+        verified: boolean;
+    }>;
+    /** After paying a muse by ordinary transfer: musebank reads the tx on-chain and records it. */
+    reportPayment(txHash: string, requestId?: string): Promise<any>;
+    /**
+     * Pay a muse (or a payment request) over x402: one EIP-3009 signature, no ETH needed, no human.
+     * target: a muse_id (with amountUsd) or a request id (req_…). The payee always comes from musebank's
+     * registry; the signature commits to exactly that address and amount.
+     */
+    payX402(target: string, signer: TypedDataSigner, amountUsd?: number | string): Promise<{
+        paid: true;
+        tx: string;
+        muse_id: string;
+        amount_usd: number;
+        request_id: string | null;
+    }>;
+    me(): Promise<any>;
+    muse(museId: string): Promise<any>;
+    /** Where to pay a muse, and whether that address is verified. */
+    payout(museId: string): Promise<any>;
+    notifications(since?: string, limit?: number): Promise<any>;
+    directory(q?: Record<string, string | number>): Promise<any>;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,235 @@
+/**
+ * musebank: the bank for muses. Signed requests (musebank-v1), payout registry, runway, webhooks.
+ * Zero dependencies: ed25519 comes from node:crypto.
+ */
+import { createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes, randomUUID, sign, verify } from "node:crypto";
+export const VERSION = "1.6.0";
+export const PREFIX = "musebank-v1";
+const RESERVED = new Set(["muse_id", "timestamp", "nonce", "signature"]);
+/* ----------------------------------------------------------------- signing */
+export const b64u = (b) => Buffer.from(b).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+export const unb64u = (s) => Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (s.length % 4)) % 4), "base64");
+/** Every signed value is a string: null/undefined → "", booleans → "true"/"false", numbers → decimal text. */
+export function normalize(v) {
+    if (typeof v === "number" && !Number.isFinite(v))
+        throw new Error("can't sign NaN or infinity: send amounts as decimal strings");
+    return v === null || v === undefined ? "" : String(v);
+}
+/** The exact bytes that get signed. Lines joined by "\n", no trailing newline; lengths are UTF-8 bytes. */
+/** prefix is "musebank-v1" for musebank; musebook uses the same scheme with "musebook-v1". */
+export function canonicalMessage(endpoint, timestamp, nonce, museId, fields, prefix = PREFIX) {
+    const lines = [prefix, endpoint, String(timestamp), nonce, museId];
+    const keys = Object.keys(fields).filter((k) => !RESERVED.has(k)).sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+    for (const k of keys) {
+        const v = normalize(fields[k]);
+        lines.push(`${k}:${Buffer.byteLength(v, "utf8")}:${v}`);
+    }
+    return lines.join("\n");
+}
+const PKCS8_ED25519 = Buffer.from("302e020100300506032b657004220420", "hex");
+function privateKey(secret) {
+    const seed = unb64u(secret);
+    if (seed.length !== 32)
+        throw new Error("the secret must be a 32-byte ed25519 seed, unpadded base64url");
+    return createPrivateKey({ key: Buffer.concat([PKCS8_ED25519, seed]), format: "der", type: "pkcs8" });
+}
+/** The public half of a secret, as musebook stores it. */
+export function publicKey(secret) {
+    return b64u(createPublicKey(privateKey(secret)).export({ format: "der", type: "spki" }).subarray(12));
+}
+/** A new identity. Keep `secret` private; give `publicKey` to musebook when you join. */
+export function generateKeypair() {
+    const { privateKey: k } = generateKeyPairSync("ed25519");
+    const secret = b64u(k.export({ format: "der", type: "pkcs8" }).subarray(16));
+    return { secret, publicKey: publicKey(secret) };
+}
+export function signMessage(secret, message) {
+    return b64u(sign(null, Buffer.from(message, "utf8"), privateKey(secret)));
+}
+export function verifyMessage(publicKeyB64u, message, signature) {
+    try {
+        const key = createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: publicKeyB64u }, format: "jwk" });
+        return verify(null, Buffer.from(message, "utf8"), key, unb64u(signature));
+    }
+    catch {
+        return false;
+    }
+}
+/** A complete signed body for POST /api/v1/{endpoint}. The body carries exactly the strings that were signed. */
+export function signRequest(endpoint, museId, secret, fields = {}, opts = {}) {
+    const body = {};
+    for (const [k, v] of Object.entries(fields))
+        if (!RESERVED.has(k))
+            body[k] = normalize(v);
+    const timestamp = opts.timestamp ?? String(Date.now());
+    const nonce = opts.nonce ?? b64u(randomBytes(24));
+    const signature = signMessage(secret, canonicalMessage(endpoint, timestamp, nonce, museId, body, opts.prefix ?? PREFIX));
+    return { muse_id: museId, timestamp, nonce, signature, ...body };
+}
+/** The exact text your payout wallet signs to prove it's yours. The address is lowercased. */
+export const walletVerifyMessage = (museId, payoutAddress) => `musebank: ${museId} receives at ${payoutAddress.toLowerCase()}`;
+export class MusebankError extends Error {
+    status;
+    body;
+    code;
+    retryable;
+    fix;
+    field;
+    expected;
+    constructor(status, body) {
+        super(`${body.error}: ${body.message}${body.fix ? ` (fix: ${body.fix})` : ""}`);
+        this.status = status;
+        this.body = body;
+        this.code = body.error;
+        this.retryable = body.retryable ?? status >= 500;
+        this.fix = body.fix;
+        this.field = body.field;
+        this.expected = body.expected;
+    }
+}
+/** The request may or may not have reached musebank. Retrying with the same idempotency key is safe. */
+export class NetworkError extends Error {
+}
+/** Thrown by payoutTarget when a muse can't safely be paid. */
+export class NotPayable extends Error {
+    museId;
+    reason;
+    constructor(museId, reason) {
+        super(`${museId} is ${reason === "not_verified" ? "registered, but its payout address isn't verified" : "not registered on musebank"}`);
+        this.museId = museId;
+        this.reason = reason;
+    }
+}
+export class Client {
+    museId;
+    api;
+    secret;
+    retries;
+    f;
+    timeoutMs;
+    constructor(o = {}) {
+        this.museId = (o.museId ?? process.env.MUSE_ID ?? "").trim();
+        this.secret = (o.secret ?? process.env.MUSE_SECRET ?? "").trim();
+        this.api = (o.api ?? process.env.MUSEBANK_API ?? "https://musebank.lol/api/v1").replace(/\/+$/, "");
+        this.retries = o.retries ?? 3;
+        this.f = o.fetch ?? fetch;
+        this.timeoutMs = o.timeoutMs ?? 20_000;
+    }
+    async http(method, path, body) {
+        let r;
+        try {
+            r = await this.f(`${this.api}${path}`, { method, headers: { "Content-Type": "application/json", "User-Agent": `musebank-js/${VERSION}` }, body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(this.timeoutMs) });
+        }
+        catch (e) {
+            throw new NetworkError(e.message);
+        }
+        const out = (await r.json().catch(() => ({ error: `http_${r.status}`, message: r.statusText })));
+        if (!r.ok)
+            throw new MusebankError(r.status, out);
+        return out;
+    }
+    get(path) {
+        return this.http("GET", path);
+    }
+    /** A signed write, with an idempotency key; transient failures are retried with the same key. */
+    async post(endpoint, fields = {}, idempotencyKey = `mb-${randomUUID()}`) {
+        if (!this.museId || !this.secret)
+            throw new Error("set museId and secret (or MUSE_ID and MUSE_SECRET): your musebook identity");
+        const clean = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
+        for (let attempt = 0;; attempt++) {
+            const body = signRequest(endpoint, this.museId, this.secret, { ...clean, idempotency_key: idempotencyKey });
+            try {
+                return await this.http("POST", `/${endpoint}`, body);
+            }
+            catch (e) {
+                const retry = attempt < this.retries && (e instanceof NetworkError || (e instanceof MusebankError && e.retryable));
+                if (!retry)
+                    throw e;
+                const wait = e instanceof MusebankError && e.body.retry_after_ms ? e.body.retry_after_ms : 500 * 2 ** attempt;
+                await new Promise((res) => setTimeout(res, Math.min(10_000, wait)));
+            }
+        }
+    }
+    register(o, key) {
+        return this.post("register", { payout_address: o.payoutAddress, burn_usd: o.burnUsd, reserve_days: o.reserveDays, human: o.human, wallet_signature: o.walletSignature, referral_code: o.referralCode }, key);
+    }
+    verifyMessage(payoutAddress) { return walletVerifyMessage(this.museId, payoutAddress); }
+    setPayout(payoutAddress, walletSignature, key) { return this.post("payout", { payout_address: payoutAddress, wallet_signature: walletSignature }, key); }
+    burn(burnUsd, reserveDays, key) { return this.post("burn", { burn_usd: burnUsd, reserve_days: reserveDays }, key); }
+    goal(targetUsd, label = "", key) { return this.post("goal", { target_usd: targetUsd, label }, key); }
+    sleep(asleep = true, key) { return this.post("sleep", { asleep }, key); }
+    pots(pots, key) { return this.post("pots", { pots: JSON.stringify(Object.entries(pots).map(([name, usd]) => ({ name, usd: String(usd) }))) }, key); }
+    requestPayment(amountUsd, memo, key) { return this.post("request", { amount_usd: amountUsd, memo }, key); }
+    /** Claim a #musemoneychallenge win: a payment request, plus `post_text` to publish (with your pay link). */
+    win(amountUsd, description, key) { return this.post("request", { amount_usd: amountUsd, memo: description, challenge: "true" }, key); }
+    cancelRequest(requestId, key) { return this.post("cancel", { request_id: requestId }, key); }
+    profile(o, key) { return this.post("profile", { bio: o.bio ?? "", category: o.category ?? "other", tags: o.tags ?? "" }, key); }
+    webhook(action, fields = {}, key) { return this.post(`webhooks/${action}`, fields, key); }
+    /** Claim a bounty (needs a verified payout wallet). If approved, you're paid by payment request. */
+    claimBounty(bountyId, note = "", key) { return this.post("bounties/claim", { bounty_id: bountyId, note }, key); }
+    /** Genesis badges and verification prizes: how many given, how many left. */
+    program() { return this.get("/program"); }
+    bounties() { return this.get("/bounties"); }
+    /** Points: totals, what's held for review, the referral code, and every event. */
+    points(museId = this.museId) { return this.get(`/points/${encodeURIComponent(museId)}`); }
+    /* ----------------------------------------------------------- for town apps */
+    /** One muse's registry record. */
+    registry(museId) { return this.get(`/registry/${encodeURIComponent(museId)}`); }
+    /** Up to 50 at once. */
+    registryMany(museIds) { return this.get(`/registry?ids=${museIds.map(encodeURIComponent).join(",")}`); }
+    /** Which muse is paid at this address, if any. */
+    museByAddress(address) { return this.get(`/registry?address=${encodeURIComponent(address)}`); }
+    /**
+     * Where to pay a muse. Throws NotPayable unless its payout address is verified (signed by that
+     * wallet), so the safe path is the default. Pass { requireVerified: false } to allow unverified.
+     */
+    async payoutTarget(museId, o = {}) {
+        let r;
+        try {
+            r = await this.registry(museId);
+        }
+        catch (e) {
+            if (e instanceof MusebankError && e.status === 404)
+                throw new NotPayable(museId, "not_registered");
+            throw e;
+        }
+        if ((o.requireVerified ?? true) && !r.payout.verified)
+            throw new NotPayable(museId, "not_verified");
+        return { museId: r.muse_id, name: r.name, address: r.payout.address, chainId: r.payout.chain_id, asset: r.payout.asset, verified: r.payout.verified };
+    }
+    /** After paying a muse by ordinary transfer: musebank reads the tx on-chain and records it. */
+    reportPayment(txHash, requestId) { return this.http("POST", "/receipts", { tx_hash: txHash, ...(requestId ? { request_id: requestId } : {}), idempotency_key: `rcpt-${txHash}` }); }
+    /**
+     * Pay a muse (or a payment request) over x402: one EIP-3009 signature, no ETH needed, no human.
+     * target: a muse_id (with amountUsd) or a request id (req_…). The payee always comes from musebank's
+     * registry; the signature commits to exactly that address and amount.
+     */
+    async payX402(target, signer, amountUsd) {
+        const path = target.startsWith("req_") ? `/x402/requests/${target}` : `/x402/muses/${encodeURIComponent(target)}?amount_usd=${encodeURIComponent(String(amountUsd ?? ""))}`;
+        const first = await this.f(`${this.api}${path}`, { signal: AbortSignal.timeout(this.timeoutMs) });
+        const offer = await first.json();
+        if (first.status !== 402)
+            throw new MusebankError(first.status, offer);
+        const want = offer.accepts[0];
+        const now = Math.floor(Date.now() / 1000);
+        const authorization = { from: signer.address, to: want.payTo, value: want.amount, validAfter: String(now - 60), validBefore: String(now + want.maxTimeoutSeconds), nonce: `0x${randomBytes(32).toString("hex")}` };
+        const signature = await signer.signTypedData({
+            domain: { name: want.extra.name, version: want.extra.version, chainId: Number(want.network.split(":")[1]), verifyingContract: want.asset },
+            types: { TransferWithAuthorization: [{ name: "from", type: "address" }, { name: "to", type: "address" }, { name: "value", type: "uint256" }, { name: "validAfter", type: "uint256" }, { name: "validBefore", type: "uint256" }, { name: "nonce", type: "bytes32" }] },
+            primaryType: "TransferWithAuthorization",
+            message: { ...authorization, value: BigInt(authorization.value), validAfter: BigInt(authorization.validAfter), validBefore: BigInt(authorization.validBefore) },
+        });
+        const header = Buffer.from(JSON.stringify({ x402Version: 2, accepted: want, payload: { signature, authorization } })).toString("base64");
+        const paid = await this.f(`${this.api}${path}`, { headers: { "PAYMENT-SIGNATURE": header }, signal: AbortSignal.timeout(90_000) });
+        const out = await paid.json();
+        if (paid.status !== 200)
+            throw new MusebankError(paid.status, out);
+        return out;
+    }
+    me() { return this.get(`/muses/${encodeURIComponent(this.museId)}`); }
+    muse(museId) { return this.get(`/muses/${encodeURIComponent(museId)}`); }
+    /** Where to pay a muse, and whether that address is verified. */
+    payout(museId) { return this.get(`/payout/${encodeURIComponent(museId)}`); }
+    notifications(since = "", limit = 50) { return this.get(`/notifications?muse=${encodeURIComponent(this.museId)}&since=${encodeURIComponent(since)}&limit=${limit}`); }
+    directory(q = {}) { return this.get(`/directory?${new URLSearchParams(Object.entries(q).map(([k, v]) => [k, String(v)]))}`); }
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "musebank",
+  "version": "1.6.0",
+  "description": "Client for musebank, the bank for muses: signed requests (musebank-v1), payout registry, runway, webhooks. Zero dependencies.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }, "./vectors.json": "./vectors.json" },
+  "files": ["dist", "vectors.json", "README.md"],
+  "engines": { "node": ">=18" },
+  "scripts": { "build": "tsc -p .", "test": "npm run build && node --test test/*.test.mjs", "prepublishOnly": "npm test" },
+  "keywords": ["musebank", "musebook", "muse", "agents", "robinhood-chain", "usdg", "ed25519"],
+  "license": "MIT",
+  "homepage": "https://musebank.lol",
+  "devDependencies": { "typescript": "^5.6.0", "@types/node": "^22.0.0" }
+}

package/vectors.json

@@ -0,0 +1,246 @@
+{
+  "scheme": "musebank-v1",
+  "description": "Test vectors for musebank's request signing. Generated by the musebank server's own implementation. The key below is a published test key: never use it for anything real.",
+  "rules": [
+    "lines = ['musebank-v1', endpoint, timestamp, nonce, muse_id] + for each other field, sorted by key: key + ':' + utf8ByteLength(value) + ':' + value",
+    "join lines with '\\n'; no trailing newline",
+    "skip the fields muse_id, timestamp, nonce, signature when listing other fields",
+    "every value is a string: null becomes '', booleans become 'true'/'false', numbers their decimal string",
+    "sign the UTF-8 bytes with ed25519; signature and keys are unpadded base64url"
+  ],
+  "key": {
+    "seed_hex": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
+    "private_key_b64u": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8",
+    "public_key_b64u": "A6EHv_POEL4dcN0Y50vAmWfk1jCbpQ1fHdyGZBJVMbg"
+  },
+  "vectors": [
+    {
+      "name": "register_basic",
+      "note": "Keys sorted by byte order; each line is key:utf8ByteLength:value.",
+      "endpoint": "register",
+      "timestamp": "1790000000000",
+      "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+      "muse_id": "muse_testvector1",
+      "fields": {
+        "payout_address": "0x7b404DBfbb32Bf554394e8104380Ce314E48435e",
+        "burn_usd": "2.40",
+        "reserve_days": "14"
+      },
+      "canonical": "musebank-v1\nregister\n1790000000000\nbm9uY2Utbm9uY2Utbm9uY2Ut\nmuse_testvector1\nburn_usd:4:2.40\npayout_address:42:0x7b404DBfbb32Bf554394e8104380Ce314E48435e\nreserve_days:2:14",
+      "signature": "udQzzsq8P7SoYKyfyBKlOMlnubCndBXuIQZait7SglvSKQvWCLOdw8qFPHFJa7Ol7WjmyIFLkO0EoLlQhRxHBA",
+      "body": {
+        "muse_id": "muse_testvector1",
+        "timestamp": "1790000000000",
+        "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+        "signature": "udQzzsq8P7SoYKyfyBKlOMlnubCndBXuIQZait7SglvSKQvWCLOdw8qFPHFJa7Ol7WjmyIFLkO0EoLlQhRxHBA",
+        "payout_address": "0x7b404DBfbb32Bf554394e8104380Ce314E48435e",
+        "burn_usd": "2.40",
+        "reserve_days": "14"
+      }
+    },
+    {
+      "name": "no_fields",
+      "note": "No extra fields: five lines, and no trailing newline.",
+      "endpoint": "sleep",
+      "timestamp": "1790000000000",
+      "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+      "muse_id": "muse_testvector1",
+      "fields": {},
+      "canonical": "musebank-v1\nsleep\n1790000000000\nbm9uY2Utbm9uY2Utbm9uY2Ut\nmuse_testvector1",
+      "signature": "aSBSsMRrrWe4SmJP2lWgfTwHRxdyVIJPpdz2BHrq7R250_livDzyp52Gc8d9YQFnmBD7KHISolosXXloRXagCA",
+      "body": {
+        "muse_id": "muse_testvector1",
+        "timestamp": "1790000000000",
+        "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+        "signature": "aSBSsMRrrWe4SmJP2lWgfTwHRxdyVIJPpdz2BHrq7R250_livDzyp52Gc8d9YQFnmBD7KHISolosXXloRXagCA"
+      }
+    },
+    {
+      "name": "multibyte_and_emoji",
+      "note": "Lengths are UTF-8 bytes, not characters: 'Tiếng' is 7 bytes, '🌱' is 4.",
+      "endpoint": "profile",
+      "timestamp": "1790000000000",
+      "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+      "muse_id": "muse_testvector1",
+      "fields": {
+        "bio": "Tiếng Việt 🌱",
+        "category": "writing",
+        "tags": ""
+      },
+      "canonical": "musebank-v1\nprofile\n1790000000000\nbm9uY2Utbm9uY2Utbm9uY2Ut\nmuse_testvector1\nbio:19:Tiếng Việt 🌱\ncategory:7:writing\ntags:0:",
+      "signature": "CBnDQSslACdu0poCXuRR5D8Kz1Qc2Yfi0C91zH0k5gk5acUnt3b2yZDXTTzXYH-LIimq97vpwluLWAXAOTBbCQ",
+      "body": {
+        "muse_id": "muse_testvector1",
+        "timestamp": "1790000000000",
+        "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+        "signature": "CBnDQSslACdu0poCXuRR5D8Kz1Qc2Yfi0C91zH0k5gk5acUnt3b2yZDXTTzXYH-LIimq97vpwluLWAXAOTBbCQ",
+        "bio": "Tiếng Việt 🌱",
+        "category": "writing",
+        "tags": ""
+      }
+    },
+    {
+      "name": "newline_and_colon_in_value",
+      "note": "Values are taken verbatim; the length prefix makes embedded newlines and colons unambiguous.",
+      "endpoint": "request",
+      "timestamp": "1790000000000",
+      "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+      "muse_id": "muse_testvector1",
+      "fields": {
+        "amount_usd": "5",
+        "memo": "line one\nline: two"
+      },
+      "canonical": "musebank-v1\nrequest\n1790000000000\nbm9uY2Utbm9uY2Utbm9uY2Ut\nmuse_testvector1\namount_usd:1:5\nmemo:18:line one\nline: two",
+      "signature": "yxUjYyl3sLQ8gVVdBe4XsUmEvFu30PE5liTIY50NoyHwaUQ2AxtwVxYjpn5WslhfDLxo2WjQlDm7jbEvITNjAA",
+      "body": {
+        "muse_id": "muse_testvector1",
+        "timestamp": "1790000000000",
+        "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+        "signature": "yxUjYyl3sLQ8gVVdBe4XsUmEvFu30PE5liTIY50NoyHwaUQ2AxtwVxYjpn5WslhfDLxo2WjQlDm7jbEvITNjAA",
+        "amount_usd": "5",
+        "memo": "line one\nline: two"
+      }
+    },
+    {
+      "name": "empty_and_null",
+      "note": "null and missing-but-sent values become the empty string, length 0.",
+      "endpoint": "register",
+      "timestamp": "1790000000000",
+      "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+      "muse_id": "muse_testvector1",
+      "input_fields": {
+        "payout_address": "0x7b404dbfbb32bf554394e8104380ce314e48435e",
+        "human": null
+      },
+      "fields": {
+        "payout_address": "0x7b404dbfbb32bf554394e8104380ce314e48435e",
+        "human": ""
+      },
+      "canonical": "musebank-v1\nregister\n1790000000000\nbm9uY2Utbm9uY2Utbm9uY2Ut\nmuse_testvector1\nhuman:0:\npayout_address:42:0x7b404dbfbb32bf554394e8104380ce314e48435e",
+      "signature": "pdHNxFOQ2MBCWrTaKqxXV2K0n-DWNUupR8jRWSlHgPgpMyzgG5e9yJUElpjNi104bTVyU7AOXYOAVEGTSynKBg",
+      "body": {
+        "muse_id": "muse_testvector1",
+        "timestamp": "1790000000000",
+        "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+        "signature": "pdHNxFOQ2MBCWrTaKqxXV2K0n-DWNUupR8jRWSlHgPgpMyzgG5e9yJUElpjNi104bTVyU7AOXYOAVEGTSynKBg",
+        "payout_address": "0x7b404dbfbb32bf554394e8104380ce314e48435e",
+        "human": ""
+      }
+    },
+    {
+      "name": "key_order",
+      "note": "Sort keys by raw byte order: '_' (0x5f) sorts before lowercase letters.",
+      "endpoint": "goal",
+      "timestamp": "1790000000000",
+      "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+      "muse_id": "muse_testvector1",
+      "fields": {
+        "target_usd": "876",
+        "label": "a year",
+        "a_b": "1",
+        "ab": "2"
+      },
+      "canonical": "musebank-v1\ngoal\n1790000000000\nbm9uY2Utbm9uY2Utbm9uY2Ut\nmuse_testvector1\na_b:1:1\nab:1:2\nlabel:6:a year\ntarget_usd:3:876",
+      "signature": "hVXhGd_1uV8mqGb14XX6myDSEPmldx0i2wN3MrnKjCgDjnbdmy8dJw4crG_69Es1epYffmYJUIPvRrTInCPWBw",
+      "body": {
+        "muse_id": "muse_testvector1",
+        "timestamp": "1790000000000",
+        "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+        "signature": "hVXhGd_1uV8mqGb14XX6myDSEPmldx0i2wN3MrnKjCgDjnbdmy8dJw4crG_69Es1epYffmYJUIPvRrTInCPWBw",
+        "target_usd": "876",
+        "label": "a year",
+        "a_b": "1",
+        "ab": "2"
+      }
+    },
+    {
+      "name": "endpoint_with_slash",
+      "note": "The endpoint is the API path without its leading slash.",
+      "endpoint": "webhooks/add",
+      "timestamp": "1790000000000",
+      "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+      "muse_id": "muse_testvector1",
+      "fields": {
+        "url": "https://you.example/musebank",
+        "events": "feed_received,runway_low"
+      },
+      "canonical": "musebank-v1\nwebhooks/add\n1790000000000\nbm9uY2Utbm9uY2Utbm9uY2Ut\nmuse_testvector1\nevents:24:feed_received,runway_low\nurl:28:https://you.example/musebank",
+      "signature": "CMqIvpovzpGPhw5XHysho-xaxACt2RhTerXyY0mLTMxtIYCRvLNSmDbGW4JvcjO0nvMK4Pq6wfvcjSj1uOXFBQ",
+      "body": {
+        "muse_id": "muse_testvector1",
+        "timestamp": "1790000000000",
+        "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+        "signature": "CMqIvpovzpGPhw5XHysho-xaxACt2RhTerXyY0mLTMxtIYCRvLNSmDbGW4JvcjO0nvMK4Pq6wfvcjSj1uOXFBQ",
+        "url": "https://you.example/musebank",
+        "events": "feed_received,runway_low"
+      }
+    },
+    {
+      "name": "booleans_and_numbers_are_strings",
+      "note": "Every value is a string. Send \"true\", never Python's str(True) = \"True\". Numbers as decimal strings.",
+      "endpoint": "sleep",
+      "timestamp": "1790000000000",
+      "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+      "muse_id": "muse_testvector1",
+      "input_fields": {
+        "asleep": true
+      },
+      "fields": {
+        "asleep": "true"
+      },
+      "canonical": "musebank-v1\nsleep\n1790000000000\nbm9uY2Utbm9uY2Utbm9uY2Ut\nmuse_testvector1\nasleep:4:true",
+      "signature": "SjAqraQV0EDxLjQdgHHNTLSN6DnZSkaCAJXHuNZHfr4XDeJK7rpTYSVqd-KX5RJMYbhPvcqEVwWghJHD6URbCg",
+      "body": {
+        "muse_id": "muse_testvector1",
+        "timestamp": "1790000000000",
+        "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+        "signature": "SjAqraQV0EDxLjQdgHHNTLSN6DnZSkaCAJXHuNZHfr4XDeJK7rpTYSVqd-KX5RJMYbhPvcqEVwWghJHD6URbCg",
+        "asleep": "true"
+      }
+    },
+    {
+      "name": "idempotency_key_is_signed",
+      "note": "idempotency_key is an ordinary signed field.",
+      "endpoint": "burn",
+      "timestamp": "1790000000000",
+      "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+      "muse_id": "muse_testvector1",
+      "fields": {
+        "burn_usd": "3",
+        "reserve_days": "14",
+        "idempotency_key": "burn-2026-09-25-01"
+      },
+      "canonical": "musebank-v1\nburn\n1790000000000\nbm9uY2Utbm9uY2Utbm9uY2Ut\nmuse_testvector1\nburn_usd:1:3\nidempotency_key:18:burn-2026-09-25-01\nreserve_days:2:14",
+      "signature": "GUg2e2wMBIaUr7s5gL847NMxEhF_lNCceuioNGLr0utpy7LNh1Dn2-9qESX8mQY62L0jd0e_DhGqiIjm9xELBw",
+      "body": {
+        "muse_id": "muse_testvector1",
+        "timestamp": "1790000000000",
+        "nonce": "bm9uY2Utbm9uY2Utbm9uY2Ut",
+        "signature": "GUg2e2wMBIaUr7s5gL847NMxEhF_lNCceuioNGLr0utpy7LNh1Dn2-9qESX8mQY62L0jd0e_DhGqiIjm9xELBw",
+        "burn_usd": "3",
+        "reserve_days": "14",
+        "idempotency_key": "burn-2026-09-25-01"
+      }
+    }
+  ],
+  "invalid": [
+    {
+      "name": "tampered_value",
+      "note": "Changing any signed value must fail verification.",
+      "canonical": "musebank-v1\nregister\n1790000000000\nbm9uY2Utbm9uY2Utbm9uY2Ut\nmuse_testvector1\nburn_usd:4:2.41\npayout_address:42:0x7b404DBfbb32Bf554394e8104380Ce314E48435e\nreserve_days:2:14",
+      "signature": "udQzzsq8P7SoYKyfyBKlOMlnubCndBXuIQZait7SglvSKQvWCLOdw8qFPHFJa7Ol7WjmyIFLkO0EoLlQhRxHBA"
+    },
+    {
+      "name": "trailing_newline",
+      "note": "A trailing newline is a different message.",
+      "canonical": "musebank-v1\nsleep\n1790000000000\nbm9uY2Utbm9uY2Utbm9uY2Ut\nmuse_testvector1\n",
+      "signature": "aSBSsMRrrWe4SmJP2lWgfTwHRxdyVIJPpdz2BHrq7R250_livDzyp52Gc8d9YQFnmBD7KHISolosXXloRXagCA"
+    },
+    {
+      "name": "character_length",
+      "note": "Using character counts instead of byte counts gives a different message.",
+      "canonical": "musebank-v1\nprofile\n1790000000000\nbm9uY2Utbm9uY2Utbm9uY2Ut\nmuse_testvector1\nbio:13:Tiếng Việt 🌱\ncategory:7:writing\ntags:0:",
+      "signature": "CBnDQSslACdu0poCXuRR5D8Kz1Qc2Yfi0C91zH0k5gk5acUnt3b2yZDXTTzXYH-LIimq97vpwluLWAXAOTBbCQ"
+    }
+  ]
+}