@coin-voyage/paykit-headless 0.0.1

package/README.md

@@ -0,0 +1,82 @@
+# @coin-voyage/paykit-headless
+
+Headless helpers for CoinVoyage PayKit and x402 payments.
+
+## x402 Agent Payments
+
+Install the package in the agent runtime:
+
+```bash
+npm install @coin-voyage/paykit-headless
+```
+
+Use `executeX402AgentPayment` when the agent should fetch a `PAYMENT-REQUIRED` challenge, create a
+`PAYMENT-SIGNATURE`, and retry the protected resource:
+
+```ts
+import { executeX402AgentPayment } from "@coin-voyage/paykit-headless/x402"
+
+const result = await executeX402AgentPayment({
+  url:
+    "https://example.com/api/agent/payment-required" +
+    "?preferred_chain_type=SUI" +
+    "&preferred_chain_id=30000000000002" +
+    "&preferred_token_address=0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
+  network: "sui:mainnet",
+  asset: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
+  maxAmount: "20000",
+  chainType: "SUI",
+  privateKey: process.env.X402_AGENT_SUI_PRIVATE_KEY,
+})
+
+if (!result.ok) {
+  throw new Error(result.message)
+}
+```
+
+Do not request `?preferred_chain_type=SUI` by itself. If you send an `X402RequirementRequest`, include
+`preferred_chain_type` and `preferred_token_address` together. If you do not have a preferred token,
+omit all preference fields and choose from the returned `accepts[]` entries.
+
+For a challenge that was already fetched, pass the `PAYMENT-REQUIRED` header:
+
+```ts
+import { createSuiX402PaymentSignatureHeader } from "@coin-voyage/paykit-headless/x402"
+
+const { paymentSignature } = await createSuiX402PaymentSignatureHeader(paymentRequiredHeader, {
+  network: "sui:mainnet",
+  asset: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
+  maxAmount: "20000",
+  privateKey: process.env.X402_AGENT_SUI_PRIVATE_KEY,
+  rpcUrl: process.env.X402_AGENT_SUI_RPC_URL,
+})
+```
+
+## Sui Payload Contract
+
+Sui x402 support uses a CoinVoyage-specific payload carried in the standard base64
+`PAYMENT-SIGNATURE` header. The package:
+
+- Selects the returned `sui:mainnet` `accepts[]` entry without changing `scheme`, `network`,
+  `asset`, `amount`, `payTo`, or `paymentIdentifier`.
+- Builds a Sui programmable transaction block that transfers the exact raw `amount` of the exact
+  coin type to `payTo`.
+- Signs the transaction with the configured Sui Ed25519 key.
+- Encodes `payload.transaction`, `payload.signatures`, `payload.signature`, and `payload.payer`.
+
+If the server provides prepared Sui transaction bytes in `accept.transactionBytes`, `accept.txBytes`,
+`accept.extra.sui.transactionBytes`, or `accept.extra.sui.txBytes`, the package signs those bytes
+instead of constructing a transfer transaction.
+
+## Required Keys
+
+Use rail-specific private keys when possible:
+
+```bash
+X402_AGENT_EVM_PRIVATE_KEY=
+X402_AGENT_SVM_PRIVATE_KEY=
+X402_AGENT_SUI_PRIVATE_KEY=
+```
+
+Pass the private key that matches the request `chainType`. `X402_AGENT_PRIVATE_KEY` can be used as a
+local fallback, but separate rail-specific keys are safer for agents.

package/dist/http.d.ts

@@ -0,0 +1 @@
+export declare function readResponseBody<TBody = unknown>(response: Response): Promise<TBody | undefined>;

package/dist/http.js

@@ -0,0 +1,14 @@
+export async function readResponseBody(response) {
+    if (response.status === 204 || response.status === 205) {
+        return undefined;
+    }
+    const text = await response.text();
+    if (!text) {
+        return undefined;
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+        return JSON.parse(text);
+    }
+    return text;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./x402";
+export * from "./http";

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./x402";
+export * from "./http";

package/dist/x402/agent.d.ts

@@ -0,0 +1,47 @@
+import { type X402PaymentAccept, type X402PreferredChainType } from "./core";
+import { type SuiX402PaymentSignatureDebug } from "./sui";
+export type X402AgentPaymentRequest = {
+    url: string;
+    paymentRequiredHeader?: string;
+    network?: string;
+    asset?: string;
+    paymentIdentifier?: string;
+    maxAmount?: string | bigint;
+    privateKey?: string;
+    chainType: X402PreferredChainType;
+    fetchFn?: typeof fetch;
+};
+export type X402AgentPaymentResult = {
+    ok: boolean;
+    message: string;
+    paymentSignatureCreated?: boolean;
+    paymentSignatureDebug?: X402PaymentSignatureDebug;
+    settlementTxHash?: string;
+    status?: number;
+    paymentResponse?: unknown;
+    body?: unknown;
+    paymentRequired?: unknown;
+};
+export type X402PaymentSignatureDebug = {
+    accepted?: {
+        network?: string;
+        asset?: string;
+        amount?: string;
+        payTo?: string;
+        paymentIdentifier?: string;
+    };
+    svm?: {
+        feePayer?: string;
+        tokenPayer?: string;
+        signedAddresses: string[];
+        missingSignatureAddresses: string[];
+    };
+    sui?: SuiX402PaymentSignatureDebug["sui"];
+};
+export declare function executeX402AgentPayment(request: X402AgentPaymentRequest): Promise<X402AgentPaymentResult>;
+export declare function selectX402AgentPaymentAccept(accepts: X402PaymentAccept[], requested: {
+    chainType?: X402PreferredChainType;
+    network?: string;
+    asset?: string;
+    paymentIdentifier?: string;
+}): X402PaymentAccept | undefined;

package/dist/x402/agent.js

@@ -0,0 +1,383 @@
+import { readResponseBody } from "../http";
+import { decodeX402PaymentRequiredHeader, decodeX402PaymentResponseHeader, selectPaymentAccept, X402_PAYMENT_REQUIRED_HEADER, X402_PAYMENT_RESPONSE_HEADER, X402_PAYMENT_SIGNATURE_HEADER, } from "./core";
+import { createSuiPaymentSignatureDebug, createSuiX402PaymentSignatureHeader, ExactSuiScheme, isSuiNetwork, } from "./sui";
+import { base58, base64, hex } from "@scure/base";
+import { createKeyPairSignerFromBytes, createKeyPairSignerFromPrivateKeyBytes } from "@solana/kit";
+import { x402Client } from "@x402/core/client";
+import { encodePaymentSignatureHeader } from "@x402/core/http";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { wrapFetchWithPayment } from "@x402/fetch";
+import { decodeTransactionFromPayload, getTokenPayerFromTransaction } from "@x402/svm";
+import { ExactSvmScheme } from "@x402/svm/exact/client";
+import { privateKeyToAccount } from "viem/accounts";
+export async function executeX402AgentPayment(request) {
+    if (request.paymentRequiredHeader) {
+        return executePreparedX402AgentPayment(request.url, request);
+    }
+    if (request.chainType !== "SUI") {
+        return executeOfficialX402AgentPayment(request.url, request);
+    }
+    return executeSuiX402AgentPayment(request.url, request);
+}
+async function executePreparedX402AgentPayment(targetUrl, request) {
+    const fetchImpl = request.fetchFn ?? fetch;
+    const paymentRequired = decodeX402PaymentRequiredHeader(request.paymentRequiredHeader);
+    const selected = selectX402AgentPaymentAccept(paymentRequired.accepts, request);
+    if (!selected) {
+        return {
+            ok: false,
+            message: "No compatible x402 payment option found for the selected accepts[] entry.",
+            paymentRequired,
+        };
+    }
+    const signatureResult = isSuiNetwork(selected.network)
+        ? await createSuiX402PaymentSignatureHeader(request.paymentRequiredHeader, {
+            network: selected.network,
+            asset: selected.assetAddress ?? selected.asset,
+            paymentIdentifier: selected.paymentIdentifier,
+            maxAmount: request.maxAmount,
+            privateKey: request.privateKey,
+        }).catch((error) => ({
+            error: error instanceof Error ? error.message : "Failed to create Sui x402 payment signature.",
+        }))
+        : await createOfficialX402PaymentSignature(request.paymentRequiredHeader, {
+            ...request,
+            network: selected.network,
+            asset: selected.assetAddress ?? selected.asset,
+            paymentIdentifier: selected.paymentIdentifier,
+        }).catch((error) => ({
+            error: error instanceof Error ? error.message : "Failed to create x402 payment signature.",
+        }));
+    if ("error" in signatureResult) {
+        return {
+            ok: false,
+            message: signatureResult.error,
+            paymentRequired,
+        };
+    }
+    const paymentSignatureDebug = getPaymentSignatureDebug(signatureResult);
+    const paidResponse = await fetchImpl(targetUrl, {
+        cache: "no-store",
+        headers: {
+            [X402_PAYMENT_SIGNATURE_HEADER]: signatureResult.paymentSignature,
+        },
+    });
+    const paymentResponseHeader = paidResponse.headers.get(X402_PAYMENT_RESPONSE_HEADER);
+    const paymentResponse = paymentResponseHeader ? decodeX402PaymentResponseHeader(paymentResponseHeader) : undefined;
+    const body = await readResponseBody(paidResponse);
+    if (!paidResponse.ok) {
+        return {
+            ok: false,
+            message: "I generated PAYMENT-SIGNATURE, but the paid retry did not complete successfully.",
+            paymentSignatureCreated: true,
+            paymentSignatureDebug,
+            status: paidResponse.status,
+            paymentResponse,
+            body,
+        };
+    }
+    const txHash = extractSettlementTxHash(paymentResponse);
+    return {
+        ok: true,
+        message: txHash
+            ? `Payment completed. Settlement transaction: ${txHash}`
+            : "Payment completed. The backend did not return a settlement transaction hash.",
+        paymentSignatureCreated: true,
+        paymentSignatureDebug,
+        status: paidResponse.status,
+        paymentResponse,
+        body,
+        settlementTxHash: txHash,
+    };
+}
+async function executeOfficialX402AgentPayment(targetUrl, request) {
+    const fetchImpl = request.fetchFn ?? fetch;
+    const client = await createX402Client(request);
+    const fetchWithPayment = wrapFetchWithPayment(fetchImpl, client);
+    const response = await fetchWithPayment(targetUrl, { cache: "no-store" });
+    const paymentResponseHeader = response.headers.get(X402_PAYMENT_RESPONSE_HEADER);
+    const paymentResponse = paymentResponseHeader ? decodeX402PaymentResponseHeader(paymentResponseHeader) : undefined;
+    const body = await readResponseBody(response);
+    if (!response.ok) {
+        return {
+            ok: false,
+            message: "I attempted the x402 payment, but the paid request did not complete successfully.",
+            status: response.status,
+            paymentResponse,
+            body,
+        };
+    }
+    const txHash = extractSettlementTxHash(paymentResponse);
+    return {
+        ok: true,
+        message: txHash
+            ? `Payment completed. Settlement transaction: ${txHash}`
+            : "Payment completed. The backend did not return a settlement transaction hash.",
+        status: response.status,
+        paymentResponse,
+        body,
+        settlementTxHash: txHash,
+    };
+}
+async function createX402Client(request) {
+    assertNetworkMatchesChainType(request.network, request.chainType);
+    if (!request.privateKey) {
+        throw new Error(`A privateKey is required for ${request.chainType} x402 payments.`);
+    }
+    const client = new x402Client();
+    if (request.chainType === "EVM") {
+        const evmSigner = privateKeyToAccount(asHex(request.privateKey));
+        client.register("eip155:*", new ExactEvmScheme(evmSigner));
+        return client;
+    }
+    if (request.chainType === "SOL") {
+        const svmSigner = await createSolanaSigner(request.privateKey);
+        client.register("solana:*", new ExactSvmScheme(svmSigner));
+        return client;
+    }
+    if (request.chainType === "SUI") {
+        client.register("sui:*", new ExactSuiScheme({ privateKey: request.privateKey }));
+        return client;
+    }
+    throw new Error(`Unsupported x402 chainType: ${request.chainType}`);
+}
+async function createOfficialX402PaymentSignature(paymentRequiredHeader, requested) {
+    const paymentRequired = decodeX402PaymentRequiredHeader(paymentRequiredHeader);
+    const selected = selectX402AgentPaymentAccept(paymentRequired.accepts, requested);
+    if (!selected) {
+        throw new Error("No compatible x402 payment option found for the requested chain or token.");
+    }
+    selectPaymentAccept(paymentRequired, {
+        paymentIdentifier: selected.paymentIdentifier,
+        network: selected.network,
+        asset: selected.assetAddress ?? selected.asset,
+        maxAmount: requested.maxAmount,
+    });
+    if (isUnsupportedNativeExactAccept(selected)) {
+        throw new Error("Native ETH and native SOL x402 accepts are not currently supported by PayKit headless. Use a token accept such as USDC, or have the server return a prepared native transaction/signature format.");
+    }
+    const client = await createX402Client({
+        ...requested,
+        network: selected.network,
+    });
+    const paymentPayload = await client.createPaymentPayload({
+        ...paymentRequired,
+        accepts: [selected],
+    });
+    return {
+        paymentSignature: encodePaymentSignatureHeader(paymentPayload),
+        debug: createPaymentSignatureDebug(paymentPayload),
+    };
+}
+function getPaymentSignatureDebug(signatureResult) {
+    return signatureResult.debug;
+}
+function createPaymentSignatureDebug(paymentPayload) {
+    if (!isRecord(paymentPayload))
+        return undefined;
+    const accepted = isRecord(paymentPayload.accepted) ? paymentPayload.accepted : undefined;
+    const payload = isRecord(paymentPayload.payload) ? paymentPayload.payload : undefined;
+    const debug = {
+        ...(accepted
+            ? {
+                accepted: {
+                    network: typeof accepted.network === "string" ? accepted.network : undefined,
+                    asset: typeof accepted.asset === "string" ? accepted.asset : undefined,
+                    amount: typeof accepted.amount === "string" ? accepted.amount : undefined,
+                    payTo: typeof accepted.payTo === "string" ? accepted.payTo : undefined,
+                    paymentIdentifier: typeof accepted.paymentIdentifier === "string" ? accepted.paymentIdentifier : undefined,
+                },
+            }
+            : {}),
+    };
+    if (payload && typeof payload.transaction === "string") {
+        if (typeof accepted?.network === "string" && isSuiNetwork(accepted.network)) {
+            const suiDebug = createSuiPaymentSignatureDebug(paymentPayload);
+            debug.sui = suiDebug.sui;
+        }
+        else {
+            try {
+                const transaction = decodeTransactionFromPayload({ transaction: payload.transaction });
+                const signatureEntries = Object.entries(transaction.signatures ?? {});
+                const extra = isRecord(accepted?.extra) ? accepted.extra : undefined;
+                debug.svm = {
+                    feePayer: typeof extra?.feePayer === "string" ? extra.feePayer : undefined,
+                    tokenPayer: getTokenPayerFromTransaction(transaction) || undefined,
+                    signedAddresses: signatureEntries.filter(([, signature]) => Boolean(signature)).map(([address]) => address),
+                    missingSignatureAddresses: signatureEntries.filter(([, signature]) => !signature).map(([address]) => address),
+                };
+            }
+            catch {
+                return debug;
+            }
+        }
+    }
+    return debug.accepted || debug.svm || debug.sui ? debug : undefined;
+}
+async function executeSuiX402AgentPayment(targetUrl, request) {
+    const fetchImpl = request.fetchFn ?? fetch;
+    const initialResponse = await fetchImpl(targetUrl, { cache: "no-store" });
+    const paymentRequiredHeader = initialResponse.headers.get(X402_PAYMENT_REQUIRED_HEADER);
+    if (initialResponse.status !== 402 || !paymentRequiredHeader) {
+        const initialResponseBody = await readResponseBody(initialResponse);
+        return {
+            ok: false,
+            message: "I could not get a PAYMENT-REQUIRED challenge from the x402 resource.",
+            status: initialResponse.status,
+            body: initialResponseBody,
+        };
+    }
+    const paymentRequired = decodeX402PaymentRequiredHeader(paymentRequiredHeader);
+    const paymentSignatureResult = await createSuiX402PaymentSignatureHeader(paymentRequiredHeader, {
+        network: request.network,
+        asset: request.asset,
+        paymentIdentifier: request.paymentIdentifier,
+        maxAmount: request.maxAmount,
+        privateKey: request.privateKey,
+    }).catch((error) => ({
+        error: error instanceof Error ? error.message : "Failed to create Sui x402 payment signature.",
+    }));
+    if ("error" in paymentSignatureResult) {
+        return {
+            ok: false,
+            message: paymentSignatureResult.error,
+            paymentRequired,
+        };
+    }
+    const paymentSignatureDebug = getPaymentSignatureDebug(paymentSignatureResult);
+    const paidResponse = await fetchImpl(targetUrl, {
+        cache: "no-store",
+        headers: {
+            [X402_PAYMENT_SIGNATURE_HEADER]: paymentSignatureResult.paymentSignature,
+        },
+    });
+    const paymentResponseHeader = paidResponse.headers.get(X402_PAYMENT_RESPONSE_HEADER);
+    const paymentResponse = paymentResponseHeader ? decodeX402PaymentResponseHeader(paymentResponseHeader) : undefined;
+    const body = await readResponseBody(paidResponse);
+    if (!paidResponse.ok) {
+        return {
+            ok: false,
+            message: "I attempted the payment, but the paid retry did not complete successfully.",
+            paymentSignatureCreated: true,
+            paymentSignatureDebug,
+            status: paidResponse.status,
+            paymentResponse,
+            body,
+        };
+    }
+    const txHash = extractSettlementTxHash(paymentResponse);
+    return {
+        ok: true,
+        message: txHash
+            ? `Payment completed. Settlement transaction: ${txHash}`
+            : "Payment completed. The backend did not return a settlement transaction hash.",
+        status: paidResponse.status,
+        paymentResponse,
+        body,
+        paymentSignatureCreated: true,
+        paymentSignatureDebug,
+        settlementTxHash: txHash,
+    };
+}
+export function selectX402AgentPaymentAccept(accepts, requested) {
+    const normalizedNetwork = requested.network?.toLowerCase();
+    return accepts.find((accept) => {
+        if (requested.chainType && !networkMatchesChainType(accept.network, requested.chainType))
+            return false;
+        if (requested.paymentIdentifier && accept.paymentIdentifier !== requested.paymentIdentifier)
+            return false;
+        if (requested.asset && !assetsMatch(accept.network, accept.assetAddress ?? accept.asset, requested.asset))
+            return false;
+        if (!normalizedNetwork || normalizedNetwork === "auto")
+            return true;
+        if (normalizedNetwork === "evm")
+            return accept.network.startsWith("eip155:");
+        if (normalizedNetwork === "solana")
+            return accept.network.startsWith("solana:");
+        if (normalizedNetwork === "sui")
+            return accept.network.startsWith("sui:");
+        return accept.network.toLowerCase() === normalizedNetwork;
+    });
+}
+function assertNetworkMatchesChainType(network, chainType) {
+    if (!networkMatchesChainType(network, chainType)) {
+        throw new Error(`network ${network} does not match chainType ${chainType}.`);
+    }
+}
+function networkMatchesChainType(network, chainType) {
+    const normalizedNetwork = network?.toLowerCase();
+    if (!normalizedNetwork || normalizedNetwork === "auto")
+        return true;
+    if (chainType === "EVM") {
+        return normalizedNetwork === "evm" || normalizedNetwork.startsWith("eip155:");
+    }
+    if (chainType === "SOL") {
+        return normalizedNetwork === "sol" || normalizedNetwork === "solana" || normalizedNetwork.startsWith("solana:");
+    }
+    if (chainType === "SUI") {
+        return normalizedNetwork === "sui" || normalizedNetwork.startsWith("sui:");
+    }
+    return false;
+}
+function isUnsupportedNativeExactAccept(accept) {
+    const network = accept.network.toLowerCase();
+    const asset = (accept.assetAddress ?? accept.asset)?.trim().toLowerCase();
+    const isNativeEth = network.startsWith("eip155:") &&
+        (!asset ||
+            asset === "native" ||
+            asset === "eth" ||
+            asset === "native-eth" ||
+            asset === "native_eth" ||
+            asset === "native:eth" ||
+            asset === "0x0000000000000000000000000000000000000000" ||
+            asset === "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee");
+    const isNativeSol = network.startsWith("solana:") &&
+        (!asset ||
+            asset === "native" ||
+            asset === "sol" ||
+            asset === "native-sol" ||
+            asset === "native_sol" ||
+            asset === "native:sol" ||
+            asset === "11111111111111111111111111111111");
+    return isNativeEth || isNativeSol;
+}
+async function createSolanaSigner(privateKey) {
+    const bytes = decodePrivateKeyBytes(privateKey.trim());
+    if (bytes.length === 64) {
+        return createKeyPairSignerFromBytes(bytes);
+    }
+    if (bytes.length === 32) {
+        return createKeyPairSignerFromPrivateKeyBytes(bytes);
+    }
+    throw new Error("Solana private key must be a 32-byte seed or 64-byte secret key.");
+}
+function decodePrivateKeyBytes(privateKey) {
+    const hexValue = privateKey.startsWith("0x") ? privateKey.slice(2) : privateKey;
+    if (hexValue.length % 2 === 0 && /^[0-9a-fA-F]+$/.test(hexValue)) {
+        return hex.decode(hexValue);
+    }
+    try {
+        return base58.decode(privateKey);
+    }
+    catch {
+        return base64.decode(privateKey);
+    }
+}
+function extractSettlementTxHash(paymentResponse) {
+    if (typeof paymentResponse !== "object" || paymentResponse === null)
+        return undefined;
+    const value = paymentResponse.settlementTxHash;
+    return typeof value === "string" ? value : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assetsMatch(network, left, right) {
+    return normalizeAssetForNetwork(left, network) === normalizeAssetForNetwork(right, network);
+}
+function normalizeAssetForNetwork(asset, network) {
+    return network.toLowerCase().startsWith("eip155:") && asset.startsWith("0x") ? asset.toLowerCase() : asset;
+}
+function asHex(value) {
+    return value.startsWith("0x") ? value : `0x${value}`;
+}

package/dist/x402/core.d.ts

@@ -0,0 +1,61 @@
+export declare const X402_PAYMENT_REQUIRED_HEADER = "PAYMENT-REQUIRED";
+export declare const X402_PAYMENT_SIGNATURE_HEADER = "PAYMENT-SIGNATURE";
+export declare const X402_PAYMENT_RESPONSE_HEADER = "PAYMENT-RESPONSE";
+export type X402Network = `eip155:${number}` | `solana:${string}` | `sui:${string}` | string;
+export type X402PaymentAccept = {
+    scheme: "exact" | string;
+    network: X402Network;
+    asset: `0x${string}` | string;
+    assetAddress?: `0x${string}` | string;
+    amount: string;
+    payTo: `0x${string}` | string;
+    paymentIdentifier: string;
+    maxTimeoutSeconds?: number;
+    extra?: {
+        name?: string;
+        version?: string;
+        assetTransferMethod?: "eip3009" | "permit2" | string;
+        [key: string]: unknown;
+    };
+    expiresAt?: string;
+    [key: string]: unknown;
+};
+export type X402PaymentRequired = {
+    x402Version?: number;
+    accepts: X402PaymentAccept[];
+    metadata?: X402Metadata;
+    resource?: Record<string, unknown>;
+    extensions?: Record<string, unknown>;
+};
+export type X402Metadata = {
+    payOrderId: string;
+    organizationId: string;
+    purpose?: string;
+    [key: string]: unknown;
+};
+export type X402PreferredChainType = "EVM" | "SOL" | "SUI";
+export type X402RequirementRequest = {
+    preferred_chain_type: X402PreferredChainType;
+    preferred_chain_id?: number;
+    preferred_token_address: `0x${string}` | string;
+};
+export type X402PreparedPayment = {
+    x402Version?: number;
+    scheme: "exact" | string;
+    network: X402Network;
+    accepted?: X402PaymentAccept;
+    paymentIdentifier: string;
+    payload: Record<string, unknown>;
+    signature?: string;
+};
+export type X402AcceptSelectionOptions = {
+    network?: string;
+    asset?: string;
+    paymentIdentifier?: string;
+    maxAmount?: string | bigint;
+    now?: Date;
+};
+export declare function decodeX402PaymentRequiredHeader(header: string): X402PaymentRequired;
+export declare function decodeX402PaymentResponseHeader(header: string): unknown;
+export declare function createPreparedX402PaymentSignatureHeader(paymentRequiredHeader: string, payment: X402PreparedPayment, options?: X402AcceptSelectionOptions): string;
+export declare function selectPaymentAccept(paymentRequired: X402PaymentRequired, options: X402AcceptSelectionOptions): X402PaymentAccept;

package/dist/x402/core.js

@@ -0,0 +1,69 @@
+import { base64 } from "@scure/base";
+export const X402_PAYMENT_REQUIRED_HEADER = "PAYMENT-REQUIRED";
+export const X402_PAYMENT_SIGNATURE_HEADER = "PAYMENT-SIGNATURE";
+export const X402_PAYMENT_RESPONSE_HEADER = "PAYMENT-RESPONSE";
+export function decodeX402PaymentRequiredHeader(header) {
+    const paymentRequired = decodeBase64Json(header);
+    if (!Array.isArray(paymentRequired.accepts) || paymentRequired.accepts.length === 0) {
+        throw new Error("Invalid PAYMENT-REQUIRED header: accepts must contain at least one payment option");
+    }
+    return paymentRequired;
+}
+export function decodeX402PaymentResponseHeader(header) {
+    return decodeBase64Json(header);
+}
+export function createPreparedX402PaymentSignatureHeader(paymentRequiredHeader, payment, options = {}) {
+    const paymentRequired = decodeX402PaymentRequiredHeader(paymentRequiredHeader);
+    selectPaymentAccept(paymentRequired, {
+        ...options,
+        network: payment.network,
+        asset: payment.accepted?.asset ?? payment.accepted?.assetAddress ?? options.asset,
+        paymentIdentifier: payment.paymentIdentifier,
+    });
+    return encodeBase64Json(payment);
+}
+export function selectPaymentAccept(paymentRequired, options) {
+    const accepted = paymentRequired.accepts.find((accept) => {
+        if (accept.scheme !== "exact")
+            return false;
+        if (options.network && accept.network !== options.network)
+            return false;
+        if (options.asset && !assetsMatch(accept.network, accept.assetAddress ?? accept.asset, options.asset))
+            return false;
+        if (options.paymentIdentifier && accept.paymentIdentifier !== options.paymentIdentifier)
+            return false;
+        return true;
+    });
+    if (!accepted) {
+        throw new Error("No compatible x402 payment option found");
+    }
+    if (options.maxAmount !== undefined && BigInt(accepted.amount) > BigInt(options.maxAmount)) {
+        throw new Error("x402 payment amount exceeds maxAmount");
+    }
+    if (accepted.expiresAt) {
+        const expiresAtMs = parseX402DateTime(accepted.expiresAt);
+        if (expiresAtMs <= (options.now ?? new Date()).getTime()) {
+            throw new Error("x402 payment requirement has expired");
+        }
+    }
+    return accepted;
+}
+function parseX402DateTime(value) {
+    const timestamp = new Date(value).getTime();
+    if (Number.isNaN(timestamp)) {
+        throw new Error(`Invalid x402 payment requirement expiration: ${value}`);
+    }
+    return timestamp;
+}
+function assetsMatch(network, left, right) {
+    return normalizeAssetForNetwork(left, network) === normalizeAssetForNetwork(right, network);
+}
+function normalizeAssetForNetwork(asset, network) {
+    return network.toLowerCase().startsWith("eip155:") && asset.startsWith("0x") ? asset.toLowerCase() : asset;
+}
+function encodeBase64Json(value) {
+    return base64.encode(new TextEncoder().encode(JSON.stringify(value)));
+}
+function decodeBase64Json(value) {
+    return JSON.parse(new TextDecoder().decode(base64.decode(value)));
+}

package/dist/x402/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./core";
+export * from "./agent";
+export * from "./sui";

package/dist/x402/index.js

@@ -0,0 +1,3 @@
+export * from "./core";
+export * from "./agent";
+export * from "./sui";

package/dist/x402/sui.d.ts

@@ -0,0 +1,60 @@
+import { x402Client } from "@x402/core/client";
+import type { Network, PaymentPayload, PaymentPayloadResult, PaymentRequirements, SchemeNetworkClient } from "@x402/core/types";
+declare const COINVOYAGE_SUI_X402_PAYLOAD_VERSION = "coinvoyage-sui-ptb-v1";
+export type SuiX402SignerOptions = {
+    privateKey?: string;
+    rpcUrl?: string;
+};
+export type SuiX402PaymentSignatureOptions = SuiX402SignerOptions & {
+    network?: string;
+    asset?: string;
+    paymentIdentifier?: string;
+    maxAmount?: string | bigint;
+};
+export type SuiX402PaymentPayload = {
+    version: typeof COINVOYAGE_SUI_X402_PAYLOAD_VERSION;
+    transaction: string;
+    txBytes: string;
+    transactionBytes: string;
+    signature: string;
+    signatures: string[];
+    payer: string;
+    amount: string;
+    payTo: string;
+    asset: string;
+    assetAddress?: string;
+    coinType: string;
+    paymentIdentifier?: string;
+};
+export type SuiX402PaymentSignatureDebug = {
+    accepted: {
+        network: string;
+        asset: string;
+        amount: string;
+        payTo: string;
+        paymentIdentifier?: string;
+    };
+    sui: {
+        payer: string;
+        coinType: string;
+        transactionBytes: string;
+        signatures: string[];
+    };
+};
+export declare class ExactSuiScheme implements SchemeNetworkClient {
+    private readonly options;
+    readonly scheme = "exact";
+    constructor(options: SuiX402SignerOptions);
+    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements): Promise<PaymentPayloadResult>;
+}
+export declare function registerExactSuiScheme(client: x402Client, options: SuiX402SignerOptions & {
+    networks?: Network[];
+}): x402Client;
+export declare function createSuiX402PaymentSignatureHeader(paymentRequiredHeader: string, options: SuiX402PaymentSignatureOptions): Promise<{
+    paymentSignature: string;
+    paymentPayload: PaymentPayload;
+    debug: SuiX402PaymentSignatureDebug;
+}>;
+export declare function createSuiPaymentSignatureDebug(paymentPayload: PaymentPayload): SuiX402PaymentSignatureDebug;
+export declare function isSuiNetwork(network?: string): boolean;
+export {};

package/dist/x402/sui.js

@@ -0,0 +1,308 @@
+import { decodeX402PaymentRequiredHeader, selectPaymentAccept, } from "./core";
+import { SuiJsonRpcClient } from "@mysten/sui/jsonRpc";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { Transaction as SuiTransaction } from "@mysten/sui/transactions";
+import { base58, base64, hex } from "@scure/base";
+import { encodePaymentSignatureHeader } from "@x402/core/http";
+const SUI_NATIVE_COIN_TYPE = "0x2::sui::SUI";
+const SUI_MAINNET_RPC_URL = "https://fullnode.mainnet.sui.io:443";
+const COINVOYAGE_SUI_X402_PAYLOAD_VERSION = "coinvoyage-sui-ptb-v1";
+export class ExactSuiScheme {
+    constructor(options) {
+        this.options = options;
+        this.scheme = "exact";
+    }
+    async createPaymentPayload(x402Version, paymentRequirements) {
+        if (!this.options.privateKey) {
+            throw new Error("A Sui private key is required for Sui x402 payments.");
+        }
+        const accept = paymentRequirements;
+        const txBytes = getPreparedSuiTransactionBytes(accept);
+        const signed = txBytes
+            ? await signSuiTransaction(txBytes, this.options.privateKey, getSuiCoinType(accept))
+            : await createAndSignSuiTransferTransaction(accept, {
+                ...this.options,
+                privateKey: this.options.privateKey,
+            });
+        return {
+            x402Version,
+            payload: createSuiSignedTransactionPayload(accept, signed),
+        };
+    }
+}
+export function registerExactSuiScheme(client, options) {
+    const networks = options.networks ?? ["sui:*"];
+    const scheme = new ExactSuiScheme(options);
+    for (const network of networks) {
+        client.register(network, scheme);
+    }
+    return client;
+}
+export async function createSuiX402PaymentSignatureHeader(paymentRequiredHeader, options) {
+    if (!options.privateKey) {
+        throw new Error("A Sui private key is required for Sui x402 payments.");
+    }
+    const paymentRequired = decodeX402PaymentRequiredHeader(paymentRequiredHeader);
+    const selected = selectSuiX402PaymentAccept(paymentRequired.accepts, options);
+    if (!selected) {
+        throw new Error("No compatible Sui x402 payment option found for the requested chain or token.");
+    }
+    selectPaymentAccept(paymentRequired, {
+        paymentIdentifier: selected.paymentIdentifier,
+        network: selected.network,
+        asset: selected.assetAddress ?? selected.asset,
+        maxAmount: options.maxAmount,
+    });
+    const scheme = new ExactSuiScheme(options);
+    const partialPayload = await scheme.createPaymentPayload(paymentRequired.x402Version ?? 2, selected);
+    const paymentPayload = createSuiPaymentPayload(paymentRequired, selected, partialPayload);
+    return {
+        paymentSignature: encodePaymentSignatureHeader(paymentPayload),
+        paymentPayload,
+        debug: createSuiPaymentSignatureDebug(paymentPayload),
+    };
+}
+export function createSuiPaymentSignatureDebug(paymentPayload) {
+    const accepted = paymentPayload.accepted;
+    const payload = paymentPayload.payload;
+    return {
+        accepted: {
+            network: accepted.network,
+            asset: accepted.assetAddress ?? accepted.asset,
+            amount: accepted.amount,
+            payTo: accepted.payTo,
+            paymentIdentifier: accepted.paymentIdentifier,
+        },
+        sui: {
+            payer: payload.payer,
+            coinType: payload.coinType,
+            transactionBytes: payload.transaction,
+            signatures: payload.signatures,
+        },
+    };
+}
+export function isSuiNetwork(network) {
+    const normalizedNetwork = network?.toLowerCase();
+    return normalizedNetwork === "sui" || normalizedNetwork?.startsWith("sui:") === true;
+}
+function createSuiPaymentPayload(paymentRequired, selected, partialPayload) {
+    return {
+        x402Version: partialPayload.x402Version,
+        resource: paymentRequired.resource,
+        accepted: selected,
+        payload: partialPayload.payload,
+        extensions: mergeExtensions(paymentRequired.extensions, partialPayload.extensions),
+    };
+}
+function mergeExtensions(serverExtensions, schemeExtensions) {
+    if (!schemeExtensions)
+        return serverExtensions;
+    if (!serverExtensions)
+        return schemeExtensions;
+    const merged = { ...serverExtensions };
+    for (const [key, value] of Object.entries(schemeExtensions)) {
+        const serverValue = merged[key];
+        merged[key] =
+            isRecord(serverValue) && isRecord(value)
+                ? {
+                    ...serverValue,
+                    ...value,
+                }
+                : value;
+    }
+    return merged;
+}
+function selectSuiX402PaymentAccept(accepts, requested) {
+    const normalizedNetwork = requested.network?.toLowerCase();
+    return accepts.find((accept) => {
+        if (!isSuiNetwork(accept.network))
+            return false;
+        if (requested.paymentIdentifier && accept.paymentIdentifier !== requested.paymentIdentifier)
+            return false;
+        if (requested.asset && !assetsMatch(accept.network, accept.assetAddress ?? accept.asset, requested.asset)) {
+            return false;
+        }
+        if (!normalizedNetwork || normalizedNetwork === "auto" || normalizedNetwork === "sui")
+            return true;
+        return accept.network.toLowerCase() === normalizedNetwork;
+    });
+}
+function createSuiSignedTransactionPayload(accept, signed) {
+    const asset = accept.assetAddress ?? accept.asset;
+    return {
+        version: COINVOYAGE_SUI_X402_PAYLOAD_VERSION,
+        transaction: signed.txBytes,
+        txBytes: signed.txBytes,
+        transactionBytes: signed.txBytes,
+        signature: signed.signature,
+        signatures: [signed.signature],
+        payer: signed.payer,
+        amount: accept.amount,
+        payTo: accept.payTo,
+        asset,
+        ...(accept.assetAddress ? { assetAddress: accept.assetAddress } : {}),
+        coinType: signed.coinType,
+        ...(accept.paymentIdentifier ? { paymentIdentifier: accept.paymentIdentifier } : {}),
+    };
+}
+function getPreparedSuiTransactionBytes(accept) {
+    const extraSui = isRecord(accept.extra?.sui) ? accept.extra.sui : undefined;
+    const value = accept.transactionBytes ?? accept.txBytes ?? extraSui?.transactionBytes ?? extraSui?.txBytes;
+    return value === undefined ? undefined : toBytes(value);
+}
+function toBytes(value) {
+    if (value instanceof Uint8Array)
+        return value;
+    if (Array.isArray(value)) {
+        if (!value.every((byte) => Number.isInteger(byte) && byte >= 0 && byte <= 255)) {
+            throw new Error("Transaction byte array must contain byte values");
+        }
+        return Uint8Array.from(value);
+    }
+    if (typeof value !== "string") {
+        throw new Error("Transaction bytes must be a string or byte array");
+    }
+    const normalized = value.trim();
+    const hexValue = normalized.startsWith("0x") ? normalized.slice(2) : normalized;
+    if (hexValue.length % 2 === 0 && /^[0-9a-fA-F]+$/.test(hexValue)) {
+        return hex.decode(hexValue);
+    }
+    return base64.decode(normalized);
+}
+async function createAndSignSuiTransferTransaction(accept, options) {
+    const keypair = createSuiKeypair(options.privateKey);
+    const payer = keypair.toSuiAddress();
+    const client = createSuiClient(options.rpcUrl);
+    const tx = new SuiTransaction();
+    const amount = BigInt(accept.amount);
+    const coinType = getSuiCoinType(accept);
+    if (!accept.payTo) {
+        throw new Error("Selected Sui x402 payment option did not include payTo.");
+    }
+    if (amount <= 0n) {
+        throw new Error("Selected Sui x402 payment amount must be greater than zero.");
+    }
+    tx.setSender(payer);
+    if (isSuiNativeCoin(coinType)) {
+        const [paymentCoin] = tx.splitCoins(tx.gas, [amount]);
+        tx.transferObjects([paymentCoin], accept.payTo);
+    }
+    else {
+        const paymentCoin = await createExactSuiTokenCoin(tx, client, {
+            owner: payer,
+            coinType,
+            amount,
+        });
+        tx.transferObjects([paymentCoin], accept.payTo);
+    }
+    const gasPrice = await client.core.getReferenceGasPrice();
+    tx.setGasPrice(gasPrice.referenceGasPrice);
+    const signed = await tx.sign({ client, signer: keypair });
+    return {
+        txBytes: signed.bytes,
+        signature: signed.signature,
+        payer,
+        coinType,
+    };
+}
+async function createExactSuiTokenCoin(tx, client, options) {
+    const coins = await getSuiCoinsForAmount(client, options);
+    const primaryCoin = tx.object(coins[0].objectId);
+    const remainingCoins = coins.slice(1).map((coin) => tx.object(coin.objectId));
+    const total = coins.reduce((sum, coin) => sum + BigInt(coin.balance), 0n);
+    if (remainingCoins.length > 0) {
+        tx.mergeCoins(primaryCoin, remainingCoins);
+    }
+    if (total === options.amount) {
+        return primaryCoin;
+    }
+    const [paymentCoin] = tx.splitCoins(primaryCoin, [options.amount]);
+    return paymentCoin;
+}
+async function getSuiCoinsForAmount(client, options) {
+    const coins = [];
+    let total = 0n;
+    let cursor = null;
+    do {
+        const page = await client.core.listCoins({
+            owner: options.owner,
+            coinType: options.coinType,
+            cursor,
+        });
+        for (const coin of page.objects) {
+            coins.push({
+                objectId: coin.objectId,
+                balance: coin.balance,
+            });
+            total += BigInt(coin.balance);
+            if (total >= options.amount)
+                return coins;
+        }
+        cursor = page.hasNextPage ? page.cursor : null;
+    } while (cursor);
+    throw new Error(`Insufficient Sui coin balance for ${options.coinType}: need ${options.amount.toString()}, found ${total.toString()}.`);
+}
+function createSuiClient(rpcUrl) {
+    return new SuiJsonRpcClient({
+        network: "mainnet",
+        url: rpcUrl ?? SUI_MAINNET_RPC_URL,
+    });
+}
+async function signSuiTransaction(transactionBytes, privateKey, coinType) {
+    const keypair = createSuiKeypair(privateKey);
+    const signed = await keypair.signTransaction(transactionBytes);
+    return {
+        txBytes: signed.bytes,
+        signature: signed.signature,
+        payer: keypair.toSuiAddress(),
+        coinType,
+    };
+}
+function createSuiKeypair(privateKey) {
+    const normalized = privateKey.trim();
+    if (normalized.startsWith("suiprivkey")) {
+        return Ed25519Keypair.fromSecretKey(normalized);
+    }
+    const bytes = decodePrivateKeyBytes(normalized);
+    const secretKey = bytes.length === 64 ? bytes.slice(0, 32) : bytes;
+    if (secretKey.length !== 32) {
+        throw new Error("Sui private key must be a 32-byte seed, 64-byte keypair, or suiprivkey string.");
+    }
+    return Ed25519Keypair.fromSecretKey(secretKey);
+}
+function decodePrivateKeyBytes(privateKey) {
+    const hexValue = privateKey.startsWith("0x") ? privateKey.slice(2) : privateKey;
+    if (hexValue.length % 2 === 0 && /^[0-9a-fA-F]+$/.test(hexValue)) {
+        return hex.decode(hexValue);
+    }
+    try {
+        return base58.decode(privateKey);
+    }
+    catch {
+        return base64.decode(privateKey);
+    }
+}
+function getSuiCoinType(accept) {
+    const asset = (accept.assetAddress ?? accept.asset)?.trim();
+    if (!asset)
+        return SUI_NATIVE_COIN_TYPE;
+    return isSuiNativeCoin(asset) ? SUI_NATIVE_COIN_TYPE : asset;
+}
+function isSuiNativeCoin(asset) {
+    const normalized = asset.toLowerCase();
+    return (normalized === SUI_NATIVE_COIN_TYPE.toLowerCase() ||
+        normalized === "native" ||
+        normalized === "sui" ||
+        normalized === "native-sui" ||
+        normalized === "native_sui" ||
+        normalized === "native:sui");
+}
+function assetsMatch(network, left, right) {
+    return normalizeAssetForNetwork(left, network) === normalizeAssetForNetwork(right, network);
+}
+function normalizeAssetForNetwork(asset, network) {
+    return network.toLowerCase().startsWith("eip155:") && asset.startsWith("0x") ? asset.toLowerCase() : asset;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@coin-voyage/paykit-headless",
+  "description": "Headless CoinVoyage PayKit clients and protocol helpers.",
+  "version": "0.0.1",
+  "private": false,
+  "sideEffects": false,
+  "author": "Lars <lars@coinvoyage.io>",
+  "homepage": "https://coinvoyage.io",
+  "license": "BSD-2-Clause license",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./x402": {
+      "import": "./dist/x402/index.js",
+      "types": "./dist/x402/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "coin-voyage",
+    "paykit",
+    "headless",
+    "x402"
+  ],
+  "dependencies": {
+    "@mysten/sui": "2.16.2",
+    "@scure/base": "2.2.0",
+    "@solana/kit": "6.9.0",
+    "@x402/core": "^2.11.0",
+    "@x402/evm": "^2.11.0",
+    "@x402/fetch": "^2.11.0",
+    "@x402/svm": "^2.11.0",
+    "viem": "2.41.2"
+  },
+  "scripts": {
+    "watch": "tsc -w -p ./tsconfig.json",
+    "build": "tsc --build --force",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "release:build": "pnpm clean && pnpm build",
+    "pre:release": "pnpm version prerelease --preid=beta",
+    "pre:publish": "pnpm publish --access public --tag beta --no-git-checks",
+    "pre:steps": "pnpm pre:release && pnpm release:build && pnpm pre:publish",
+    "release": "pnpm publish --access public --no-git-checks",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit"
+  }
+}