@payagent/wdk-protocol 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# `@payagent/wdk-protocol`
+
+PayAgent protocol for Tether WDK. **Not a wallet.** You pass a WDK `WalletAccount`. This package never sees a seed.
+
+v1: `preflight` + `pay` for a payment link, profile, or address. USDT/USDC (and catalog natives) on Ethereum, Base, Solana.
+
+See `docs/wdk-status.md` for what is built and tested, and `docs/wdk-protocol-implementation.md` for the fail-closed rules.
+
+```ts
+import { PayAgentProtocol } from "@payagent/wdk-protocol";
+
+const protocol = new PayAgentProtocol(account, {
+  baseUrl: "https://www.payagent.co",
+  apiKey: process.env.PAYAGENT_API_KEY!,
+  agentId: "your-agent-id",
+  networkId: "ethereum",
+});
+
+const result = await protocol.pay({
+  type: "link",
+  linkUsername: "alice",
+  linkId: "link_public_id",
+});
+```
+
+If `pay` throws `RecordFailedError`, the transfer already landed. Call `protocol.record(...)` with the same `txHash` and `idempotencyKey`. Do not transfer again.
+
+## Staging script (real WDK, not the Next app)
+
+This is how WDK is wired to PayAgent today: a sidecar script, not checkout.
+
+```bash
+cp packages/wdk-protocol/env.example packages/wdk-protocol/.env
+# fill seed, staging API key, agent id, USDT link
+pnpm wdk-protocol:staging address
+pnpm wdk-protocol:staging attach
+pnpm wdk-protocol:staging preflight
+WDK_STAGING_SEND=1 pnpm wdk-protocol:staging pay --send
+```
+
+`pay` will not broadcast unless both `--send` and `WDK_STAGING_SEND=1` are set. Use a no-approval USDT policy on staging. Do not use a production treasury seed.

package/dist/amount.d.ts

@@ -0,0 +1,2 @@
+/** Exact human amount → token base units. Rejects float-unsafe numbers. */
+export declare function toBaseUnits(amount: string | number, decimals: number): bigint;

package/dist/amount.js

@@ -0,0 +1,38 @@
+import { PayAgentProtocolError } from "./errors.js";
+/** Exact human amount → token base units. Rejects float-unsafe numbers. */
+export function toBaseUnits(amount, decimals) {
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 36) {
+        throw new PayAgentProtocolError("BAD_DECIMALS", `Invalid decimals: ${decimals}`);
+    }
+    const human = typeof amount === "number"
+        ? formatNumberAsDecimalString(amount)
+        : amount.trim();
+    if (!human || human.startsWith("-") || human === "." || human === "+") {
+        throw new PayAgentProtocolError("BAD_AMOUNT", `Invalid amount: ${String(amount)}`);
+    }
+    const parts = human.split(".");
+    if (parts.length > 2) {
+        throw new PayAgentProtocolError("BAD_AMOUNT", `Invalid amount: ${human}`);
+    }
+    const whole = parts[0] === "" ? "0" : parts[0];
+    const fraction = parts[1] ?? "";
+    if (!/^\d+$/.test(whole) || (fraction.length > 0 && !/^\d+$/.test(fraction))) {
+        throw new PayAgentProtocolError("BAD_AMOUNT", `Invalid amount: ${human}`);
+    }
+    if (fraction.length > decimals) {
+        throw new PayAgentProtocolError("AMOUNT_PRECISION", `Amount ${human} has more than ${decimals} decimal places`);
+    }
+    const padded = fraction.padEnd(decimals, "0");
+    const base = 10n ** BigInt(decimals);
+    return BigInt(whole) * base + BigInt(padded || "0");
+}
+function formatNumberAsDecimalString(amount) {
+    if (!Number.isFinite(amount) || amount <= 0) {
+        throw new PayAgentProtocolError("BAD_AMOUNT", `Invalid amount: ${amount}`);
+    }
+    const text = amount.toString();
+    if (/e/i.test(text)) {
+        throw new PayAgentProtocolError("BAD_AMOUNT", "Pass the amount as a decimal string to avoid scientific notation");
+    }
+    return text;
+}

package/dist/catalog.d.ts

@@ -0,0 +1,13 @@
+export type CatalogAsset = {
+    networkId: string;
+    tokenId: string;
+    decimals: number;
+    kind: "erc20" | "spl" | "native";
+    address?: string;
+};
+export declare function lookupAsset(networkId: string, tokenId: string): CatalogAsset;
+export declare function isEvmNetwork(networkId: string): networkId is "ethereum" | "base" | "sepolia";
+export declare function isSolanaNetwork(networkId: string): networkId is "solana";
+export declare function isEvmAddress(address: string): boolean;
+export declare function isSolanaAddress(address: string): boolean;
+export declare function sameAddress(a: string, b: string, networkId: string): boolean;

package/dist/catalog.js

@@ -0,0 +1,102 @@
+import { PayAgentProtocolError } from "./errors.js";
+const catalog = [
+    {
+        networkId: "ethereum",
+        tokenId: "usdt",
+        decimals: 6,
+        kind: "erc20",
+        address: "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+    },
+    {
+        networkId: "ethereum",
+        tokenId: "usdc",
+        decimals: 6,
+        kind: "erc20",
+        address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    },
+    {
+        networkId: "ethereum",
+        tokenId: "lcx",
+        decimals: 18,
+        kind: "erc20",
+        address: "0x8CD41041505885EF0aD3858181D66f17BE8aae7E",
+    },
+    { networkId: "ethereum", tokenId: "eth", decimals: 18, kind: "native" },
+    {
+        networkId: "base",
+        tokenId: "usdt",
+        decimals: 6,
+        kind: "erc20",
+        address: "0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2",
+    },
+    {
+        networkId: "base",
+        tokenId: "usdc",
+        decimals: 6,
+        kind: "erc20",
+        address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    },
+    { networkId: "base", tokenId: "eth", decimals: 18, kind: "native" },
+    {
+        networkId: "solana",
+        tokenId: "usdt",
+        decimals: 6,
+        kind: "spl",
+        address: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
+    },
+    {
+        networkId: "solana",
+        tokenId: "usdc",
+        decimals: 6,
+        kind: "spl",
+        address: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+    },
+    { networkId: "solana", tokenId: "sol", decimals: 9, kind: "native" },
+    {
+        networkId: "sepolia",
+        tokenId: "usdt",
+        decimals: 6,
+        kind: "erc20",
+        address: "0xF9E0643Ba46eeaf4e1059775567f67F5c867bbfc",
+    },
+    {
+        networkId: "sepolia",
+        tokenId: "usdc",
+        decimals: 6,
+        kind: "erc20",
+        address: "0x3402d41AA8e34e0DF605c12109de2f8F4FF33A87",
+    },
+    {
+        networkId: "sepolia",
+        tokenId: "lcx",
+        decimals: 18,
+        kind: "erc20",
+        address: "0x98d99c88D31C27C5a591Fe7F023F9DB0B37E4B3b",
+    },
+    { networkId: "sepolia", tokenId: "eth", decimals: 18, kind: "native" },
+];
+export function lookupAsset(networkId, tokenId) {
+    const asset = catalog.find((item) => item.networkId === networkId && item.tokenId === tokenId);
+    if (!asset) {
+        throw new PayAgentProtocolError("UNSUPPORTED_ASSET", `Unsupported token ${tokenId} on ${networkId}`);
+    }
+    return asset;
+}
+export function isEvmNetwork(networkId) {
+    return networkId === "ethereum" || networkId === "base" || networkId === "sepolia";
+}
+export function isSolanaNetwork(networkId) {
+    return networkId === "solana";
+}
+export function isEvmAddress(address) {
+    return /^0x[a-fA-F0-9]{40}$/.test(address.trim());
+}
+export function isSolanaAddress(address) {
+    return /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(address.trim());
+}
+export function sameAddress(a, b, networkId) {
+    if (isEvmNetwork(networkId)) {
+        return a.trim().toLowerCase() === b.trim().toLowerCase();
+    }
+    return a.trim() === b.trim();
+}

package/dist/client.d.ts

@@ -0,0 +1,13 @@
+export type HttpClient = {
+    get(path: string, query?: Record<string, string | undefined>): Promise<unknown>;
+    post(path: string, body: unknown, headers?: Record<string, string>): Promise<{
+        status: number;
+        body: unknown;
+    }>;
+};
+export declare function createHttpClient(input: {
+    baseUrl: string;
+    apiKey: string;
+    fetchImpl: typeof fetch;
+}): HttpClient;
+export declare function newIdempotencyKey(): string;

package/dist/client.js

@@ -0,0 +1,69 @@
+import { PayAgentProtocolError } from "./errors.js";
+export function createHttpClient(input) {
+    const baseUrl = input.baseUrl.replace(/\/$/, "");
+    async function request(path, init) {
+        const headers = new Headers(init.headers);
+        if (!headers.has("Authorization")) {
+            headers.set("Authorization", `Bearer ${input.apiKey}`);
+        }
+        if (init.body && !headers.has("Content-Type")) {
+            headers.set("Content-Type", "application/json");
+        }
+        const response = await input.fetchImpl(`${baseUrl}${path}`, {
+            ...init,
+            headers,
+        });
+        const text = await response.text();
+        let body = null;
+        if (text) {
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                body = text;
+            }
+        }
+        return { status: response.status, body };
+    }
+    return {
+        async get(path, query = {}) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(query)) {
+                if (value != null && value !== "")
+                    params.set(key, value);
+            }
+            const suffix = params.size > 0 ? `?${params}` : "";
+            const { status, body } = await request(`${path}${suffix}`, { method: "GET" });
+            if (status < 200 || status >= 300) {
+                const message = typeof body === "object" && body && "error" in body
+                    ? String(body.error)
+                    : `GET ${path} failed (${status})`;
+                throw new PayAgentProtocolError("HTTP_ERROR", message);
+            }
+            return body;
+        },
+        async post(path, body, extraHeaders = {}) {
+            return request(path, {
+                method: "POST",
+                body: JSON.stringify(body),
+                headers: extraHeaders,
+            });
+        },
+    };
+}
+export function newIdempotencyKey() {
+    if (typeof globalThis.crypto?.randomUUID === "function") {
+        return globalThis.crypto.randomUUID();
+    }
+    const bytes = new Uint8Array(16);
+    if (typeof globalThis.crypto?.getRandomValues === "function") {
+        globalThis.crypto.getRandomValues(bytes);
+    }
+    else {
+        throw new PayAgentProtocolError("NO_CRYPTO", "crypto.randomUUID is required to build an Idempotency-Key");
+    }
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+export declare class PayAgentProtocolError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class PreflightDeniedError extends PayAgentProtocolError {
+    readonly checks: unknown;
+    constructor(message: string, checks: unknown);
+}
+export declare class RecordFailedError extends PayAgentProtocolError {
+    readonly txHash: string;
+    readonly idempotencyKey: string;
+    readonly status: number;
+    readonly body: unknown;
+    constructor(input: {
+        txHash: string;
+        idempotencyKey: string;
+        status: number;
+        body: unknown;
+        message?: string;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,31 @@
+export class PayAgentProtocolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "PayAgentProtocolError";
+        this.code = code;
+    }
+}
+export class PreflightDeniedError extends PayAgentProtocolError {
+    checks;
+    constructor(message, checks) {
+        super("PREFLIGHT_DENIED", message);
+        this.name = "PreflightDeniedError";
+        this.checks = checks;
+    }
+}
+export class RecordFailedError extends PayAgentProtocolError {
+    txHash;
+    idempotencyKey;
+    status;
+    body;
+    constructor(input) {
+        super("RECORD_FAILED", input.message ??
+            `PayAgent did not record tx ${input.txHash} (HTTP ${input.status}). Retry record() with the same hash and idempotency key. Do not transfer again.`);
+        this.name = "RecordFailedError";
+        this.txHash = input.txHash;
+        this.idempotencyKey = input.idempotencyKey;
+        this.status = input.status;
+        this.body = input.body;
+    }
+}

package/dist/identity.d.ts

@@ -0,0 +1,2 @@
+import type { WdkWalletAccount } from "./types.js";
+export declare function signAgentChallenge(account: WdkWalletAccount, message: string): Promise<string>;

package/dist/identity.js

@@ -0,0 +1,11 @@
+import { PayAgentProtocolError } from "./errors.js";
+export async function signAgentChallenge(account, message) {
+    if (typeof account.sign !== "function") {
+        throw new PayAgentProtocolError("NO_SIGN", "WalletAccount.sign(message) is required to prove an agent challenge");
+    }
+    const signature = await account.sign(message);
+    if (!signature?.trim()) {
+        throw new PayAgentProtocolError("NO_SIGNATURE", "WalletAccount.sign returned no signature");
+    }
+    return signature.trim();
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { toBaseUnits } from "./amount.js";
+export { lookupAsset } from "./catalog.js";
+export { PayAgentProtocolError, PreflightDeniedError, RecordFailedError, } from "./errors.js";
+export { signAgentChallenge } from "./identity.js";
+export { PayAgentProtocol } from "./protocol.js";
+export type { AddressPayIntent, AgentChallenge, AgentProof, Destination, LinkPayIntent, PayAgentProtocolConfig, PayIntent, PayResult, PreflightResult, ProfilePayIntent, WdkWalletAccount, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { toBaseUnits } from "./amount.js";
+export { lookupAsset } from "./catalog.js";
+export { PayAgentProtocolError, PreflightDeniedError, RecordFailedError, } from "./errors.js";
+export { signAgentChallenge } from "./identity.js";
+export { PayAgentProtocol } from "./protocol.js";

package/dist/protocol.d.ts

@@ -0,0 +1,28 @@
+import type { AgentChallenge, AgentProof, Destination, PayAgentProtocolConfig, PayIntent, PayResult, PreflightResult, WdkWalletAccount } from "./types.js";
+export declare class PayAgentProtocol {
+    readonly account: WdkWalletAccount;
+    readonly config: Required<Pick<PayAgentProtocolConfig, "apiKey" | "agentId" | "networkId">> & {
+        baseUrl: string;
+    };
+    private readonly http;
+    constructor(account: WdkWalletAccount, config: PayAgentProtocolConfig);
+    preflight(intent: PayIntent): Promise<PreflightResult>;
+    pay(intent: PayIntent): Promise<PayResult>;
+    record(input: {
+        intent: PayIntent;
+        destination: Destination;
+        payerAddress: string;
+        txHash: string;
+        idempotencyKey: string;
+    }): Promise<PayResult>;
+    resolvePayee(intent: PayIntent): Promise<Destination>;
+    private preflightForPayer;
+    private transfer;
+    private intentNetwork;
+    private assertAccountFitsNetwork;
+    private assertDestinationFitsAccount;
+    issueCredential(ttlHours?: number): Promise<unknown>;
+    getPublicCredential(publicId: string): Promise<unknown>;
+    createChallenge(publicId: string): Promise<AgentChallenge>;
+    prove(publicId: string): Promise<AgentProof>;
+}

package/dist/protocol.js

@@ -0,0 +1,413 @@
+import { toBaseUnits } from "./amount.js";
+import { isEvmAddress, isEvmNetwork, isSolanaAddress, isSolanaNetwork, lookupAsset, sameAddress, } from "./catalog.js";
+import { createHttpClient, newIdempotencyKey } from "./client.js";
+import { PayAgentProtocolError, PreflightDeniedError, RecordFailedError, } from "./errors.js";
+import { signAgentChallenge } from "./identity.js";
+const APPROVAL_REQUIRED = "APPROVAL_REQUIRED";
+export class PayAgentProtocol {
+    account;
+    config;
+    http;
+    constructor(account, config) {
+        if (!account?.getAddress || !account.transfer) {
+            throw new PayAgentProtocolError("NO_ACCOUNT", "PayAgentProtocol requires a WDK WalletAccount (getAddress + transfer)");
+        }
+        if (!config.apiKey?.trim()) {
+            throw new PayAgentProtocolError("NO_API_KEY", "apiKey is required");
+        }
+        if (!config.agentId?.trim()) {
+            throw new PayAgentProtocolError("NO_AGENT_ID", "agentId is required");
+        }
+        if (!config.networkId?.trim()) {
+            throw new PayAgentProtocolError("NO_NETWORK", "networkId is required");
+        }
+        this.account = account;
+        this.config = {
+            baseUrl: (config.baseUrl ?? "https://www.payagent.co").replace(/\/$/, ""),
+            apiKey: config.apiKey.trim(),
+            agentId: config.agentId.trim(),
+            networkId: config.networkId.trim(),
+        };
+        this.http = createHttpClient({
+            baseUrl: this.config.baseUrl,
+            apiKey: this.config.apiKey,
+            fetchImpl: config.fetch ?? globalThis.fetch.bind(globalThis),
+        });
+    }
+    async preflight(intent) {
+        const payerAddress = await this.account.getAddress();
+        this.assertAccountFitsNetwork(payerAddress, this.intentNetwork(intent));
+        return this.preflightForPayer(intent, payerAddress);
+    }
+    async pay(intent) {
+        const payerAddress = await this.account.getAddress();
+        const networkId = this.intentNetwork(intent);
+        this.assertAccountFitsNetwork(payerAddress, networkId);
+        const idempotencyKey = newIdempotencyKey();
+        const preflight = await this.preflightForPayer(intent, payerAddress);
+        if (hasApprovalRequired(preflight.checks) && !intent.approvalId) {
+            return {
+                status: "approval_required",
+                checks: preflight.checks,
+                approvalId: approvalIdFromChecks(preflight.checks),
+            };
+        }
+        if (!preflight.ready) {
+            throw new PreflightDeniedError("PayAgent preflight is not ready. No transfer was sent.", preflight.checks);
+        }
+        const destination = await this.resolvePayee(intent);
+        this.assertDestinationFitsAccount(payerAddress, destination);
+        const asset = lookupAsset(destination.networkId, destination.tokenId);
+        const units = toBaseUnits(destination.amount, asset.decimals);
+        if (units <= 0n) {
+            throw new PayAgentProtocolError("BAD_AMOUNT", "Amount must be greater than zero");
+        }
+        const txHash = await this.transfer(destination.recipientAddress, asset, units);
+        if (typeof this.account.waitForTransaction === "function") {
+            try {
+                await this.account.waitForTransaction(txHash, { target: "confirmed" });
+            }
+            catch {
+                // Hash exists. Record anyway; PayAgent verify may need a retry.
+            }
+        }
+        return this.record({
+            intent,
+            destination,
+            payerAddress,
+            txHash,
+            idempotencyKey,
+        });
+    }
+    async record(input) {
+        const body = recordBody(this.config.agentId, input.payerAddress, input.txHash, input.intent, input.destination);
+        const { status, body: response } = await this.http.post("/api/v1/pay", body, {
+            "Idempotency-Key": input.idempotencyKey,
+        });
+        if (status === 202) {
+            const approvalId = readApprovalId(response);
+            return {
+                status: "approval_required",
+                txHash: input.txHash,
+                idempotencyKey: input.idempotencyKey,
+                approvalId,
+                checks: isRecord(response) && isRecord(response.checks)
+                    ? response.checks
+                    : undefined,
+            };
+        }
+        if (status < 200 || status >= 300) {
+            throw new RecordFailedError({
+                txHash: input.txHash,
+                idempotencyKey: input.idempotencyKey,
+                status,
+                body: response,
+            });
+        }
+        return {
+            status: "paid",
+            txHash: input.txHash,
+            idempotencyKey: input.idempotencyKey,
+            destination: input.destination,
+            record: response,
+        };
+    }
+    async resolvePayee(intent) {
+        if (intent.type === "link") {
+            const link = await this.http.get(`/api/pay/${encodeURIComponent(intent.linkUsername)}/${encodeURIComponent(intent.linkId)}`);
+            const parsed = parsePublicLink(link);
+            if (!parsed.recipientAddress) {
+                throw new PayAgentProtocolError("NO_RECIPIENT", "Payment link has no recipient address");
+            }
+            if (parsed.canPay === false || (parsed.status && parsed.status !== "pending")) {
+                throw new PayAgentProtocolError("LINK_NOT_PAYABLE", `Payment link is not payable (${parsed.status ?? "unknown"})`);
+            }
+            return {
+                type: "link",
+                recipientAddress: parsed.recipientAddress,
+                amount: parsed.amount,
+                tokenId: parsed.tokenId,
+                networkId: parsed.networkId,
+                linkUsername: parsed.username,
+                linkId: parsed.publicId,
+            };
+        }
+        if (intent.type === "profile") {
+            const payload = await this.http.get(`/api/public/users/${encodeURIComponent(intent.recipientUsername)}`);
+            const profile = parsePublicProfile(payload);
+            const wallet = profile.wallets.find((item) => item.networkId === intent.networkId);
+            if (!wallet?.address) {
+                throw new PayAgentProtocolError("NO_RECIPIENT", `Recipient has no verified wallet on ${intent.networkId}`);
+            }
+            return {
+                type: "profile",
+                recipientAddress: wallet.address,
+                amount: intent.amount,
+                tokenId: intent.tokenId,
+                networkId: intent.networkId,
+                recipientUsername: profile.username,
+            };
+        }
+        return {
+            type: "address",
+            recipientAddress: intent.recipientAddress,
+            amount: intent.amount,
+            tokenId: intent.tokenId,
+            networkId: intent.networkId,
+        };
+    }
+    async preflightForPayer(intent, payerAddress) {
+        const query = {
+            type: intent.type,
+            agentId: this.config.agentId,
+            payerAddress,
+        };
+        if (intent.type === "link") {
+            query.linkUsername = intent.linkUsername;
+            query.linkId = intent.linkId;
+        }
+        else if (intent.type === "profile") {
+            query.recipientUsername = intent.recipientUsername;
+            query.tokenId = intent.tokenId;
+            query.networkId = intent.networkId;
+            query.amount = String(intent.amount);
+        }
+        else {
+            query.recipientAddress = intent.recipientAddress;
+            query.tokenId = intent.tokenId;
+            query.networkId = intent.networkId;
+            query.amount = String(intent.amount);
+        }
+        const body = await this.http.get("/api/v1/pay/preflight", query);
+        return parsePreflight(body);
+    }
+    async transfer(recipient, asset, units) {
+        if (asset.kind === "native") {
+            if (typeof this.account.sendTransaction !== "function") {
+                throw new PayAgentProtocolError("NO_NATIVE_SEND", "This WalletAccount cannot send native ETH/SOL. Fund a token pay or pass sendTransaction.");
+            }
+            const result = await this.account.sendTransaction({
+                to: recipient,
+                value: units,
+            });
+            return readHash(result);
+        }
+        if (!asset.address) {
+            throw new PayAgentProtocolError("NO_TOKEN", `Missing contract/mint for ${asset.tokenId}`);
+        }
+        const result = await this.account.transfer({
+            token: asset.address,
+            recipient,
+            amount: units,
+        });
+        return readHash(result);
+    }
+    intentNetwork(intent) {
+        if (intent.type === "link")
+            return this.config.networkId;
+        return intent.networkId;
+    }
+    assertAccountFitsNetwork(payerAddress, networkId) {
+        if (isEvmNetwork(networkId) && !isEvmAddress(payerAddress)) {
+            throw new PayAgentProtocolError("NETWORK_MISMATCH", `WalletAccount ${payerAddress} is not an EVM address for ${networkId}`);
+        }
+        if (isSolanaNetwork(networkId) && !isSolanaAddress(payerAddress)) {
+            throw new PayAgentProtocolError("NETWORK_MISMATCH", `WalletAccount ${payerAddress} is not a Solana address for ${networkId}`);
+        }
+        if (isEvmNetwork(this.config.networkId) !== isEvmNetwork(networkId)) {
+            throw new PayAgentProtocolError("NETWORK_MISMATCH", `Protocol is bound to ${this.config.networkId}, intent uses ${networkId}`);
+        }
+    }
+    assertDestinationFitsAccount(payerAddress, destination) {
+        this.assertAccountFitsNetwork(payerAddress, destination.networkId);
+        if (destination.networkId !== this.config.networkId) {
+            throw new PayAgentProtocolError("NETWORK_MISMATCH", `Destination network ${destination.networkId} does not match protocol ${this.config.networkId}`);
+        }
+        if (isEvmNetwork(destination.networkId) &&
+            !isEvmAddress(destination.recipientAddress)) {
+            throw new PayAgentProtocolError("BAD_RECIPIENT", "Recipient is not a valid EVM address");
+        }
+        if (isSolanaNetwork(destination.networkId) &&
+            !isSolanaAddress(destination.recipientAddress)) {
+            throw new PayAgentProtocolError("BAD_RECIPIENT", "Recipient is not a valid Solana address");
+        }
+        if (sameAddress(payerAddress, destination.recipientAddress, destination.networkId)) {
+            throw new PayAgentProtocolError("SELF_PAY", "Payer and recipient addresses are the same");
+        }
+    }
+    async issueCredential(ttlHours) {
+        const { status, body } = await this.http.post("/api/v1/agents/credentials", {
+            agentId: this.config.agentId,
+            ttlHours,
+        });
+        if (status < 200 || status >= 300) {
+            throw new PayAgentProtocolError("CREDENTIAL_ISSUE_FAILED", httpError(body, status));
+        }
+        return body;
+    }
+    async getPublicCredential(publicId) {
+        return this.http.get(`/agents/${encodeURIComponent(publicId.trim())}/credential.json`);
+    }
+    async createChallenge(publicId) {
+        const { status, body } = await this.http.post("/api/public/agent-challenge", {
+            publicId: publicId.trim(),
+            networkId: this.config.networkId,
+        });
+        if (status < 200 || status >= 300) {
+            throw new PayAgentProtocolError("CHALLENGE_FAILED", httpError(body, status));
+        }
+        if (!isRecord(body) ||
+            typeof body.challengeId !== "string" ||
+            typeof body.message !== "string" ||
+            typeof body.publicId !== "string" ||
+            typeof body.networkId !== "string" ||
+            typeof body.expiresAt !== "string") {
+            throw new PayAgentProtocolError("CHALLENGE_FAILED", "Unexpected challenge response");
+        }
+        return {
+            challengeId: body.challengeId,
+            publicId: body.publicId,
+            networkId: body.networkId,
+            message: body.message,
+            expiresAt: body.expiresAt,
+        };
+    }
+    async prove(publicId) {
+        const address = await this.account.getAddress();
+        const challenge = await this.createChallenge(publicId);
+        const signature = await signAgentChallenge(this.account, challenge.message);
+        const { status, body } = await this.http.post("/api/public/agent-challenge/verify", {
+            challengeId: challenge.challengeId,
+            address,
+            signature,
+        });
+        if (status < 200 || status >= 300) {
+            throw new PayAgentProtocolError("PROVE_FAILED", httpError(body, status));
+        }
+        if (!isRecord(body) || body.ok !== true || typeof body.publicId !== "string") {
+            throw new PayAgentProtocolError("PROVE_FAILED", "Unexpected verify response");
+        }
+        return {
+            ok: true,
+            publicId: body.publicId,
+            address: typeof body.address === "string" ? body.address : address,
+            networkId: typeof body.networkId === "string" ? body.networkId : this.config.networkId,
+            credential: body.credential,
+        };
+    }
+}
+function httpError(body, status) {
+    if (isRecord(body) && typeof body.error === "string")
+        return body.error;
+    return `Request failed (${status})`;
+}
+function parsePreflight(body) {
+    if (!isRecord(body) || typeof body.ready !== "boolean" || !isRecord(body.checks)) {
+        throw new PayAgentProtocolError("BAD_PREFLIGHT", "Unexpected preflight response");
+    }
+    return {
+        ready: body.ready,
+        type: body.type === "profile" || body.type === "address" ? body.type : "link",
+        checks: body.checks,
+    };
+}
+function parsePublicLink(body) {
+    const link = isRecord(body) && isRecord(body.link) ? body.link : body;
+    if (!isRecord(link) ||
+        typeof link.username !== "string" ||
+        typeof link.publicId !== "string" ||
+        typeof link.tokenId !== "string" ||
+        typeof link.networkId !== "string" ||
+        (typeof link.amount !== "number" && typeof link.amount !== "string")) {
+        throw new PayAgentProtocolError("BAD_LINK", "Unexpected payment link response");
+    }
+    return {
+        username: link.username,
+        publicId: link.publicId,
+        amount: typeof link.amount === "number" ? link.amount : Number(link.amount),
+        tokenId: link.tokenId,
+        networkId: link.networkId,
+        recipientAddress: typeof link.recipientAddress === "string" ? link.recipientAddress : null,
+        canPay: typeof link.canPay === "boolean" ? link.canPay : undefined,
+        status: typeof link.status === "string" ? link.status : undefined,
+    };
+}
+function parsePublicProfile(body) {
+    const profile = isRecord(body) && isRecord(body.profile) ? body.profile : body;
+    if (!isRecord(profile) || typeof profile.username !== "string" || !Array.isArray(profile.wallets)) {
+        throw new PayAgentProtocolError("BAD_PROFILE", "Unexpected profile response");
+    }
+    return {
+        username: profile.username,
+        wallets: profile.wallets
+            .filter(isRecord)
+            .map((wallet) => ({
+            networkId: String(wallet.networkId ?? ""),
+            address: String(wallet.address ?? ""),
+        }))
+            .filter((wallet) => wallet.networkId && wallet.address),
+    };
+}
+function recordBody(agentId, payerAddress, txHash, intent, destination) {
+    const base = {
+        agentId,
+        payerAddress,
+        txHash,
+        type: destination.type,
+        approvalId: intent.approvalId,
+    };
+    if (destination.type === "link") {
+        return {
+            ...base,
+            linkUsername: destination.linkUsername,
+            linkId: destination.linkId,
+        };
+    }
+    if (destination.type === "profile") {
+        return {
+            ...base,
+            recipientUsername: destination.recipientUsername,
+            amount: Number(destination.amount),
+            tokenId: destination.tokenId,
+            networkId: destination.networkId,
+        };
+    }
+    return {
+        ...base,
+        recipientAddress: destination.recipientAddress,
+        amount: Number(destination.amount),
+        tokenId: destination.tokenId,
+        networkId: destination.networkId,
+    };
+}
+function hasApprovalRequired(checks) {
+    return Object.values(checks).some((check) => check.code === APPROVAL_REQUIRED);
+}
+function approvalIdFromChecks(checks) {
+    for (const check of Object.values(checks)) {
+        const match = /approvals\/([A-Za-z0-9]+)/.exec(check.message ?? "");
+        if (match?.[1])
+            return match[1];
+    }
+    return undefined;
+}
+function readApprovalId(body) {
+    if (!isRecord(body))
+        return undefined;
+    if (typeof body.approvalId === "string")
+        return body.approvalId;
+    if (isRecord(body.error) && typeof body.error.approvalId === "string") {
+        return body.error.approvalId;
+    }
+    return undefined;
+}
+function readHash(result) {
+    const hash = typeof result === "string" ? result : result.hash;
+    if (!hash?.trim()) {
+        throw new PayAgentProtocolError("NO_TX_HASH", "WalletAccount transfer returned no hash");
+    }
+    return hash.trim();
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/types.d.ts

@@ -0,0 +1,117 @@
+export type PayType = "link" | "profile" | "address";
+export type WdkTransferResult = {
+    hash: string;
+};
+export type WdkWalletAccount = {
+    getAddress(): Promise<string>;
+    transfer(options: {
+        token: string;
+        recipient: string;
+        amount: bigint;
+    }): Promise<WdkTransferResult>;
+    sendTransaction?(tx: {
+        to: string;
+        value: bigint;
+    }): Promise<WdkTransferResult | string>;
+    waitForTransaction?(hash: string, options?: {
+        target?: "confirmed" | "final";
+    }): Promise<unknown>;
+    /** Sign a plaintext challenge. Required only for prove(), not for pay(). */
+    sign?(message: string): Promise<string>;
+};
+export type AgentChallenge = {
+    challengeId: string;
+    publicId: string;
+    networkId: string;
+    message: string;
+    expiresAt: string;
+};
+export type AgentProof = {
+    ok: true;
+    publicId: string;
+    address: string;
+    networkId: string;
+    credential?: unknown;
+};
+export type PayAgentProtocolConfig = {
+    baseUrl?: string;
+    apiKey: string;
+    agentId: string;
+    networkId: string;
+    fetch?: typeof fetch;
+};
+export type LinkPayIntent = {
+    type: "link";
+    linkUsername: string;
+    linkId: string;
+    approvalId?: string;
+};
+export type ProfilePayIntent = {
+    type: "profile";
+    recipientUsername: string;
+    amount: string | number;
+    tokenId: string;
+    networkId: string;
+    approvalId?: string;
+};
+export type AddressPayIntent = {
+    type: "address";
+    recipientAddress: string;
+    amount: string | number;
+    tokenId: string;
+    networkId: string;
+    approvalId?: string;
+};
+export type PayIntent = LinkPayIntent | ProfilePayIntent | AddressPayIntent;
+export type PreflightCheck = {
+    ok: boolean;
+    code?: string;
+    message: string;
+};
+export type PreflightResult = {
+    ready: boolean;
+    type: PayType;
+    checks: Record<string, PreflightCheck>;
+};
+export type Destination = {
+    type: PayType;
+    recipientAddress: string;
+    amount: string | number;
+    tokenId: string;
+    networkId: string;
+    linkUsername?: string;
+    linkId?: string;
+    recipientUsername?: string;
+};
+export type ApprovalRequiredResult = {
+    status: "approval_required";
+    checks?: Record<string, PreflightCheck>;
+    approvalId?: string;
+    txHash?: string;
+    idempotencyKey?: string;
+};
+export type PaidResult = {
+    status: "paid";
+    txHash: string;
+    idempotencyKey: string;
+    destination: Destination;
+    record: unknown;
+};
+export type PayResult = ApprovalRequiredResult | PaidResult;
+export type PublicPaymentLink = {
+    username: string;
+    publicId: string;
+    amount: number;
+    tokenId: string;
+    networkId: string;
+    recipientAddress?: string | null;
+    canPay?: boolean;
+    status?: string;
+};
+export type PublicProfile = {
+    username: string;
+    wallets: Array<{
+        networkId: string;
+        address: string;
+    }>;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@payagent/wdk-protocol",
+  "version": "0.1.0",
+  "description": "WDK protocol module for PayAgent. Stateless. Takes a WalletAccount. Never holds keys.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.test.json && node --test dist-test/test/*.test.js",
+    "staging": "tsc -p tsconfig.json && node --import tsx scripts/staging-usdt-pay.ts",
+    "staging:address": "tsc -p tsconfig.json && node --import tsx scripts/staging-usdt-pay.ts address",
+    "staging:preflight": "tsc -p tsconfig.json && node --import tsx scripts/staging-usdt-pay.ts preflight",
+    "staging:attach": "tsc -p tsconfig.json && node --import tsx scripts/staging-usdt-pay.ts attach",
+    "staging:pay": "tsc -p tsconfig.json && node --import tsx scripts/staging-usdt-pay.ts pay --send"
+  },
+  "dependencies": {
+    "@tetherto/wdk": "^1.0.0-beta.17",
+    "@tetherto/wdk-wallet-evm": "^1.0.0-beta.17",
+    "@tetherto/wdk-wallet-solana": "^1.0.0-beta.15"
+  },
+  "keywords": [
+    "payagent",
+    "wdk",
+    "tether",
+    "usdt"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mrinallcx/fidence.git",
+    "directory": "packages/wdk-protocol"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.17.2",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.2"
+  }
+}