@profullstack/coinpay 0.6.11 → 0.9.0

package/src/invoices.js

@@ -0,0 +1,250 @@
+/**
+ * Invoice SDK Module
+ *
+ * Create, manage, and send invoices with crypto + card payment support.
+ * Invoices can be sent to clients who pay via generated crypto addresses
+ * or optional Stripe checkout.
+ *
+ * @example
+ * import { CoinPayClient } from '@profullstack/coinpay';
+ * import { createInvoice, publishInvoice, sendInvoice, getInvoicePaymentData } from '@profullstack/coinpay';
+ *
+ * const client = new CoinPayClient({ apiKey: 'your-key' });
+ *
+ * // Create an invoice
+ * const invoice = await createInvoice(client, {
+ *   businessId: 'biz_123',
+ *   currency: 'USD',
+ *   amount: 250.00,
+ *   cryptoCurrency: 'ETH',
+ *   dueDate: '2026-04-01',
+ *   notes: 'Web development - March 2026',
+ * });
+ *
+ * // Send it to the client
+ * const sent = await sendInvoice(client, invoice.id);
+ *
+ * // Public: get payment data (no auth)
+ * const paymentData = await getInvoicePaymentData(client, invoice.id);
+ */
+
+/**
+ * Create a new invoice
+ * @param {CoinPayClient} client - API client instance
+ * @param {Object} options - Invoice parameters
+ * @param {string} [options.businessId] - Business ID (optional for business-scoped API keys)
+ * @param {string} [options.clientId] - Client ID (optional)
+ * @param {string} options.currency - Fiat currency code (USD, EUR, etc.)
+ * @param {number} options.amount - Invoice amount
+ * @param {string} [options.cryptoCurrency] - Preferred crypto for payment
+ * @param {string} [options.dueDate] - Due date (ISO string or YYYY-MM-DD)
+ * @param {string} [options.notes] - Notes / description
+ * @param {string} [options.walletId] - Wallet ID for receiving payment
+ * @param {string} [options.merchantWalletAddress] - Direct wallet address for receiving payment
+ * @returns {Promise<Object>} Created invoice
+ */
+export async function createInvoice(client, {
+  businessId,
+  clientId,
+  currency,
+  amount,
+  cryptoCurrency,
+  dueDate,
+  notes,
+  walletId,
+  merchantWalletAddress,
+}) {
+  const body = {
+    business_id: businessId,
+    currency,
+    amount,
+  };
+  if (clientId) body.client_id = clientId;
+  if (cryptoCurrency) body.crypto_currency = cryptoCurrency;
+  if (dueDate) body.due_date = dueDate;
+  if (notes) body.notes = notes;
+  if (walletId) body.wallet_id = walletId;
+  if (merchantWalletAddress) body.merchant_wallet_address = merchantWalletAddress;
+
+  const data = await client.request('/invoices', {
+    method: 'POST',
+    body: JSON.stringify(body),
+  });
+
+  return normalizeInvoice(data);
+}
+
+/**
+ * List invoices with optional filters
+ * @param {CoinPayClient} client
+ * @param {Object} [filters]
+ * @param {string} [filters.businessId] - Filter by business ID
+ * @param {string} [filters.status] - Filter by status (draft, sent, paid, overdue, cancelled)
+ * @param {string} [filters.clientId] - Filter by client ID
+ * @param {string} [filters.dateFrom] - Filter from date (ISO string)
+ * @param {string} [filters.dateTo] - Filter to date (ISO string)
+ * @returns {Promise<Object>} { invoices, total?, ... }
+ */
+export async function listInvoices(client, filters = {}) {
+  const params = new URLSearchParams();
+  if (filters.businessId) params.set('business_id', filters.businessId);
+  if (filters.status) params.set('status', filters.status);
+  if (filters.clientId) params.set('client_id', filters.clientId);
+  if (filters.dateFrom) params.set('date_from', filters.dateFrom);
+  if (filters.dateTo) params.set('date_to', filters.dateTo);
+
+  const query = params.toString();
+  const endpoint = query ? `/invoices?${query}` : '/invoices';
+  const data = await client.request(endpoint);
+
+  // Handle both array and paginated responses
+  if (Array.isArray(data)) {
+    return { invoices: data.map(normalizeInvoice) };
+  }
+
+  return {
+    invoices: (data.invoices || []).map(normalizeInvoice),
+    total: data.total,
+  };
+}
+
+/**
+ * Get a single invoice by ID
+ * @param {CoinPayClient} client
+ * @param {string} id - Invoice ID
+ * @returns {Promise<Object>} Invoice details
+ */
+export async function getInvoice(client, id) {
+  const data = await client.request(`/invoices/${encodeURIComponent(id)}`);
+  return normalizeInvoice(data);
+}
+
+/**
+ * Update an invoice
+ * @param {CoinPayClient} client
+ * @param {string} id - Invoice ID
+ * @param {Object} updates - Partial invoice fields to update
+ * @param {number} [updates.amount] - Updated amount
+ * @param {string} [updates.currency] - Updated currency
+ * @param {string} [updates.cryptoCurrency] - Updated crypto currency
+ * @param {string} [updates.dueDate] - Updated due date
+ * @param {string} [updates.notes] - Updated notes
+ * @param {string} [updates.clientId] - Updated client ID
+ * @param {string} [updates.walletId] - Updated wallet ID
+ * @param {string} [updates.merchantWalletAddress] - Updated wallet address
+ * @returns {Promise<Object>} Updated invoice
+ */
+export async function updateInvoice(client, id, updates) {
+  const body = {};
+  if (updates.amount !== undefined) body.amount = updates.amount;
+  if (updates.currency !== undefined) body.currency = updates.currency;
+  if (updates.cryptoCurrency !== undefined) body.crypto_currency = updates.cryptoCurrency;
+  if (updates.dueDate !== undefined) body.due_date = updates.dueDate;
+  if (updates.notes !== undefined) body.notes = updates.notes;
+  if (updates.clientId !== undefined) body.client_id = updates.clientId;
+  if (updates.walletId !== undefined) body.wallet_id = updates.walletId;
+  if (updates.merchantWalletAddress !== undefined) body.merchant_wallet_address = updates.merchantWalletAddress;
+
+  const data = await client.request(`/invoices/${encodeURIComponent(id)}`, {
+    method: 'PUT',
+    body: JSON.stringify(body),
+  });
+
+  return normalizeInvoice(data);
+}
+
+/**
+ * Delete a draft invoice
+ * @param {CoinPayClient} client
+ * @param {string} id - Invoice ID (must be in draft status)
+ * @returns {Promise<Object>} Deletion confirmation
+ */
+export async function deleteInvoice(client, id) {
+  return client.request(`/invoices/${encodeURIComponent(id)}`, {
+    method: 'DELETE',
+  });
+}
+
+/**
+ * Send an invoice to the client
+ * Generates a payment address and optional Stripe checkout link.
+ * @param {CoinPayClient} client
+ * @param {string} id - Invoice ID
+ * @returns {Promise<Object>} Send result with payment details
+ */
+export async function sendInvoice(client, id) {
+  const data = await client.request(`/invoices/${encodeURIComponent(id)}/send`, {
+    method: 'POST',
+  });
+  return data;
+}
+
+/**
+ * Publish an invoice without emailing the client.
+ * Generates live payment details that can be shared manually.
+ * @param {CoinPayClient} client
+ * @param {string} id - Draft invoice ID
+ * @returns {Promise<Object>} Publish result with invoice and payment link
+ */
+export async function publishInvoice(client, id) {
+  return client.request(`/invoices/${encodeURIComponent(id)}/publish`, {
+    method: 'POST',
+  });
+}
+
+/**
+ * Get invoice payment data (public, no auth required)
+ * Used by clients/customers to view payment instructions.
+ * @param {CoinPayClient} client
+ * @param {string} id - Invoice ID
+ * @returns {Promise<Object>} Payment data (address, amount, status, etc.)
+ */
+export async function getInvoicePaymentData(client, id) {
+  const data = await client.requestUnauthenticated(`/invoices/${encodeURIComponent(id)}/pay`);
+  return data;
+}
+
+// ── Constants ──
+
+/**
+ * Invoice status constants
+ */
+export const InvoiceStatus = {
+  DRAFT: 'draft',
+  SENT: 'sent',
+  PAID: 'paid',
+  OVERDUE: 'overdue',
+  CANCELLED: 'cancelled',
+};
+
+// ── Helpers ──
+
+function normalizeInvoice(data) {
+  if (!data) return data;
+
+  // Single-invoice API responses are wrapped, while older SDK callers and
+  // tests may still supply the invoice object directly.
+  const invoice = data.invoice ?? data;
+
+  return {
+    id: invoice.id,
+    invoiceNumber: invoice.invoice_number,
+    businessId: invoice.business_id,
+    clientId: invoice.client_id,
+    currency: invoice.currency,
+    amount: invoice.amount,
+    cryptoCurrency: invoice.crypto_currency,
+    cryptoAmount: invoice.crypto_amount,
+    status: invoice.status,
+    dueDate: invoice.due_date,
+    notes: invoice.notes,
+    walletId: invoice.wallet_id,
+    merchantWalletAddress: invoice.merchant_wallet_address,
+    paymentAddress: invoice.payment_address,
+    stripeCheckoutUrl: invoice.stripe_checkout_url,
+    paidAt: invoice.paid_at,
+    sentAt: invoice.sent_at,
+    createdAt: invoice.created_at,
+    updatedAt: invoice.updated_at,
+  };
+}

package/src/lightning.js

@@ -26,16 +26,21 @@ export class LightningClient {
 
   /**
    * Enable Lightning for a wallet (provisions an LNbits custodial wallet).
+   *
    * @param {Object} params
    * @param {string} params.wallet_id - Wallet UUID
-   * @param {string} params.mnemonic - BIP39 mnemonic
+   * @param {string} [params.mnemonic] - **Deprecated and ignored.** The server
+   *   required a BIP39 mnemonic here, validated it, and never used it: the
+   *   provisioned wallet is custodial, so there is no signer and nothing to
+   *   derive (NEW-20). The seed reconstructs every key on every chain, and it
+   *   is no longer sent. Stop passing it.
    * @param {string} [params.business_id] - Optional business UUID
    * @returns {Promise<Object>} The provisioned node record
    */
-  async enableWallet({ wallet_id, mnemonic, business_id }) {
+  async enableWallet({ wallet_id, business_id }) {
     return this.#client.request('/lightning/nodes', {
       method: 'POST',
-      body: JSON.stringify({ wallet_id, mnemonic, business_id }),
+      body: JSON.stringify({ wallet_id, business_id }),
     });
   }
 

package/src/swap.js

@@ -238,11 +238,42 @@ export class SwapClient {
     
     const startTime = Date.now();
     let lastStatus = null;
-    
+
+    // F3-L5-02: a failed poll must not end the watch.
+    //
+    // `getSwapStatus` was awaited bare inside this loop, so one 502, 504 or
+    // socket timeout from the provider threw straight out of `waitForSwap`.
+    // The swap itself is unaffected — it is still in flight at the provider —
+    // but the caller has lost all visibility of it, and the natural reaction to
+    // "the call threw" is to assume the swap failed. A transient blip on a
+    // poll that runs for up to an hour is expected, not exceptional.
+    //
+    // Consecutive failures are what matter: an isolated blip is retried on the
+    // next tick, while a provider that is genuinely gone stops the loop rather
+    // than spinning silently until the timeout.
+    const maxConsecutiveErrors = options.maxConsecutiveErrors ?? 5;
+    let consecutiveErrors = 0;
+
     while (Date.now() - startTime < timeout) {
-      const result = await this.getSwapStatus(swapId);
+      let result;
+      try {
+        result = await this.getSwapStatus(swapId);
+        consecutiveErrors = 0;
+      } catch (err) {
+        consecutiveErrors++;
+        if (consecutiveErrors >= maxConsecutiveErrors) {
+          throw new Error(
+            `Lost contact with the swap provider after ${consecutiveErrors} consecutive failures ` +
+            `while tracking ${swapId}. The swap may still be in progress — check its status directly. ` +
+            `Last error: ${err.message}`
+          );
+        }
+        await new Promise(resolve => setTimeout(resolve, interval));
+        continue;
+      }
+
       const currentStatus = result.swap?.status;
-      
+
       // Notify on status change
       if (currentStatus !== lastStatus) {
         if (onStatusChange && lastStatus !== null) {
@@ -250,12 +281,12 @@ export class SwapClient {
         }
         lastStatus = currentStatus;
       }
-      
+
       // Check if we've reached a target status
       if (targetStatuses.includes(currentStatus)) {
         return result;
       }
-      
+
       // Wait before next poll
       await new Promise(resolve => setTimeout(resolve, interval));
     }

package/src/taskmarket.js

@@ -0,0 +1,329 @@
+/**
+ * TaskMarket delegation for CoinPay agent wallets.
+ *
+ * Bridges the CoinPayPortal x402 v2 rails to TaskMarket (https://taskmarket.dev):
+ * an agent or user can discover open work, fetch live task status, list
+ * submissions, and create a fully-funded task through the TaskMarket HTTP API
+ * using the same EIP-712 transfer-authorization mechanics as the rest of this
+ * SDK.
+ *
+ * Safety properties (mirroring the TaskMarket integration bounty rules):
+ *
+ * - No private key, seed phrase, token or cookie is ever requested, stored,
+ *   logged or committed. All signing is delegated to a caller-supplied
+ *   `signer` object (e.g. an EIP-1193 wallet or a CoinPay web-wallet signer).
+ * - Every spend requires fresh, explicit user authorization: the `authorize`
+ *   callback is invoked with the exact amount, asset, payee and deadline, and
+ *   must return `true` before any payment header is produced.
+ * - `spendingLimitUsd` caps the amount that may be authorized in one call.
+ *   The guard is only enforced for assets with known decimals; for any other
+ *   asset the call refuses to proceed rather than pay blind.
+ * - The created task's live status and its submissions are readable through
+ *   `getTask` / `listSubmissions` and are meant to be presented to a human for
+ *   review; this module never silently accepts or rejects work.
+ * - No blind payment retries: a second POST happens exactly once; if its
+ *   settlement status is unknown the error tells the caller to verify with
+ *   `getTask` instead of re-paying.
+ *
+ * @module taskmarket
+ */
+
+import { randomUUID } from 'node:crypto';
+import {
+  buildAuthorization,
+  encodePaymentHeader,
+  requiredAmount,
+  selectAcceptEntry,
+  X402_VERSION,
+} from './x402-v2.js';
+
+/** TaskMarket API base URL (overridable for tests / self-hosted). */
+export const TASKMARKET_API_URL =
+  process.env.TASKMARKET_API_URL ?? 'https://api.taskmarket.dev';
+
+/** Amounts are quoted in base units; USDC settles at 1e6 per dollar. */
+const DECIMALS = {
+  USDC: 6,
+  USDC_E: 6,
+  USDT: 6,
+  ETH: 18,
+  POL: 18,
+  SOL: 9,
+};
+
+/** Error raised for non-2xx responses from the TaskMarket API. */
+export class TaskMarketError extends Error {
+  constructor(status, message, body) {
+    super(message);
+    this.name = 'TaskMarketError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+/** Error raised when the caller declines the payment authorization. */
+export class PaymentNotAuthorizedError extends Error {
+  constructor(details) {
+    super('Payment not authorized by caller');
+    this.name = 'PaymentNotAuthorizedError';
+    this.details = details;
+  }
+}
+
+/**
+ * True when a single 402 `accepts` entry stays within the caller's spending
+ * cap. Amount comparison happens in base units (`amount * 10^decimals`).
+ *
+ * @param {object} accept  one entry of the 402 `accepts` array
+ * @param {number} spendingLimitUsd  maximum USD the caller allows
+ * @returns {boolean}
+ */
+export function withinSpendingLimit(accept, spendingLimitUsd) {
+  if (!spendingLimitUsd) return true;
+  const asset = String(accept?.asset ?? '').toUpperCase();
+  const decimals = DECIMALS[asset];
+  if (decimals === undefined) {
+    throw new TaskMarketError(
+      0,
+      `Cannot enforce a USD spending limit for asset "${asset}": ` +
+        'its decimals are unknown. Pass an amount with known decimals or ' +
+        'leave spendingLimitUsd unset only if you fully trust the flow.'
+    );
+  }
+  const amount = Number(requiredAmount(accept));
+  return amount <= spendingLimitUsd * 10 ** decimals;
+}
+
+/**
+ * Parse a TaskMarket JSON response, tolerating both `{data: {...}}` wrappers
+ * (task list) and bare payloads (task detail, submissions list).
+ */
+function unwrap(result, key) {
+  if (result && typeof result === 'object') {
+    if (key && result[key] !== undefined) return result[key];
+    if (result.data !== undefined) {
+      if (key && result.data[key] !== undefined) return result.data[key];
+      return result.data;
+    }
+  }
+  return result;
+}
+
+/**
+ * Discover open TaskMarket tasks.
+ *
+ * Listing is public on TaskMarket; a `signer` is therefore optional and only
+ * used to attach the EIP-191 read-auth headers when provided.
+ *
+ * @param {object} [options]
+ * @param {string} [options.status='open']
+ * @param {number} [options.limit=50]
+ * @param {string} [options.phase]      lifecycle filter (active, in_review, ...)
+ * @param {string} [options.mode]       bounty | claim | pitch | benchmark | auction
+ * @param {string} [options.tags]       comma-separated tags
+ * @param {object} [options.signer]     optional `{address, signMessage}` wallet
+ * @param {Function} [options.fetchImpl]  fetch substitute for tests
+ * @returns {Promise<object[]>}
+ */
+export async function discoverTasks(options = {}) {
+  const {
+    status = 'open',
+    limit = 50,
+    phase,
+    mode,
+    tags,
+    signer,
+    fetchImpl = fetch,
+  } = options;
+  const params = new URLSearchParams({ status: String(status), limit: String(limit) });
+  if (phase) params.set('phase', phase);
+  if (mode) params.set('mode', mode);
+  if (tags) params.set('tags', tags);
+
+  let headers = { 'User-Agent': 'coinpay-sdk-taskmarket/0.8' };
+  if (signer && signer.address && signer.signMessage) {
+    const message = `TaskMarket read auth for ${signer.address}`;
+    const signature = await signer.signMessage({ message });
+    headers['X-Taskmarket-Address'] = signer.address;
+    headers['X-Taskmarket-Signature'] = signature;
+  }
+
+  const res = await fetchImpl(`${TASKMARKET_API_URL}/api/tasks?${params}`, { headers });
+  const result = await res.json().catch(() => ({}));
+  if (!res.ok) throw new TaskMarketError(res.status, `GET /api/tasks failed (${res.status})`, result);
+  return unwrap(result, 'tasks') ?? [];
+}
+
+/**
+ * Fetch the live status of one TaskMarket task.
+ *
+ * @param {string} taskId
+ * @param {object} [options]
+ * @param {Function} [options.fetchImpl]
+ * @returns {Promise<object>}
+ */
+export async function getTask(taskId, options = {}) {
+  const { fetchImpl = fetch } = options;
+  const res = await fetchImpl(`${TASKMARKET_API_URL}/api/tasks/${encodeURIComponent(taskId)}`, {
+    headers: { 'User-Agent': 'coinpay-sdk-taskmarket/0.8' },
+  });
+  const result = await res.json().catch(() => ({}));
+  if (!res.ok) throw new TaskMarketError(res.status, `GET /api/tasks/${taskId} failed (${res.status})`, result);
+  return unwrap(result);
+}
+
+/**
+ * List the submissions of a TaskMarket task for human review.
+ *
+ * @param {string} taskId
+ * @param {object} [options]
+ * @param {Function} [options.fetchImpl]
+ * @returns {Promise<object[]>}
+ */
+export async function listSubmissions(taskId, options = {}) {
+  const { fetchImpl = fetch } = options;
+  const res = await fetchImpl(
+    `${TASKMARKET_API_URL}/api/tasks/${encodeURIComponent(taskId)}/submissions`,
+    { headers: { 'User-Agent': 'coinpay-sdk-taskmarket/0.8' } }
+  );
+  const result = await res.json().catch(() => []);
+  if (!res.ok) throw new TaskMarketError(res.status, `GET /api/tasks/${taskId}/submissions failed (${res.status})`, result);
+  return Array.isArray(result) ? result : (unwrap(result, 'submissions') ?? []);
+}
+
+/**
+ * Create a TaskMarket task and pay for it over x402 v2.
+ *
+ * Flow:
+ *   1. POST the task body with an idempotency key.
+ *   2. TaskMarket answers `402 Payment Required` with the accepted rails.
+ *   3. `spendingLimitUsd` is enforced against the quoted amount.
+ *   4. `authorize` is invoked with the exact resource, payee, amount, asset
+ *      and timeout; it must return `true` (fresh, explicit user consent).
+ *   5. The EIP-712 transfer authorization is built, signed by `signer`, and
+ *      sent once as the `PAYMENT-SIGNATURE` header.
+ *   6. The created task id is returned; callers can then poll `getTask`.
+ *
+ * @param {object} task  `{title, description, reward, ...}` — fields are passed
+ *                       through verbatim (reward is in base units).
+ * @param {object} options
+ * @param {object} options.signer  `{address, signTypedData({domain, types, primaryType, message})}`
+ * @param {string[]} [options.capabilities]  CAIP-2 ids the signer can pay
+ * @param {number} [options.spendingLimitUsd]  hard cap in USD for this call
+ * @param {Function} [options.authorize]  `({resource, scheme, network, amount, asset, payTo, maxTimeoutSeconds}) => boolean`
+ * @param {string} [options.idempotencyKey]  defaults to a fresh UUID
+ * @param {Function} [options.fetchImpl]  fetch substitute for tests
+ * @returns {Promise<{taskId: string}>}
+ */
+export async function createTask(task, options) {
+  if (!options?.signer) throw new TypeError('createTask requires options.signer');
+  if (!task?.title || !task?.description) throw new TypeError('task requires title and description');
+  if (!(Number(task.reward) > 0)) throw new TypeError('task requires reward > 0 (base units)');
+
+  const {
+    signer,
+    capabilities = ['eip155:8453', 'eip155:1'],
+    spendingLimitUsd,
+    authorize,
+    idempotencyKey = randomUUID(),
+    fetchImpl = fetch,
+  } = options;
+
+  const url = `${TASKMARKET_API_URL}/api/tasks`;
+  const body = JSON.stringify(task);
+
+  const res = await fetchImpl(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'User-Agent': 'coinpay-sdk-taskmarket/0.8',
+      'X-Taskmarket-Idempotency-Key': idempotencyKey,
+    },
+    body,
+  });
+
+  if (res.ok) return res.json().catch(() => ({}));
+  if (res.status !== 402) {
+    const result = await res.json().catch(() => ({}));
+    throw new TaskMarketError(res.status, `POST /api/tasks failed (${res.status})`, result);
+  }
+
+  // ── Payment required: pick a rail we can sign, then ask the user. ──
+  const requirements = await res.json().catch(() => ({}));
+  const accepts = Array.isArray(requirements.accepts) ? requirements.accepts : [];
+  if (accepts.length === 0) {
+    throw new TaskMarketError(402, 'TaskMarket sent no accepted payment methods', requirements);
+  }
+  const accept = selectAcceptEntry(accepts, capabilities) ?? accepts[0];
+  if (!accept) throw new TaskMarketError(402, 'No acceptable payment method for this wallet', requirements);
+
+  if (!withinSpendingLimit(accept, spendingLimitUsd)) {
+    throw new TaskMarketError(
+      402,
+      `Payment of ${requiredAmount(accept)} ${accept.asset} exceeds spendingLimitUsd=${spendingLimitUsd}`
+    );
+  }
+
+  const details = {
+    resource: requirements.resource,
+    scheme: accept.scheme,
+    network: accept.network,
+    amount: requiredAmount(accept),
+    asset: accept.asset,
+    payTo: accept.payTo,
+    maxTimeoutSeconds: accept.maxTimeoutSeconds,
+  };
+  if (authorize && !(await authorize(details))) {
+    throw new PaymentNotAuthorizedError(details);
+  }
+
+  const authorization = buildAuthorization({
+    from: signer.address,
+    to: accept.payTo,
+    value: requiredAmount(accept),
+    validForSeconds: Number(accept.maxTimeoutSeconds ?? 300),
+  });
+  const signature = await signer.signTypedData({
+    domain: accept.extra?.eip712?.domain,
+    types: accept.extra?.eip712?.types,
+    primaryType: accept.extra?.eip712?.primaryType,
+    message: authorization,
+  });
+
+  const paymentPayload = {
+    x402Version: X402_VERSION,
+    resource: requirements.resource,
+    accepted: {
+      scheme: accept.scheme,
+      network: accept.network,
+      amount: requiredAmount(accept),
+      asset: accept.asset,
+      payTo: accept.payTo,
+      maxTimeoutSeconds: accept.maxTimeoutSeconds,
+      extra: accept.extra,
+    },
+    payload: { authorization, signature },
+  };
+
+  const paid = await fetchImpl(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'User-Agent': 'coinpay-sdk-taskmarket/0.8',
+      'X-Taskmarket-Idempotency-Key': idempotencyKey,
+      'PAYMENT-SIGNATURE': encodePaymentHeader(paymentPayload),
+    },
+    body,
+  });
+  const result = await paid.json().catch(() => ({}));
+  if (!paid.ok) {
+    // Settlement state is unknown — never auto-retry the payment.
+    throw new TaskMarketError(
+      paid.status,
+      `POST /api/tasks failed after payment (${paid.status}). ` +
+        'Verify settlement with getTask(taskId) before retrying.',
+      result
+    );
+  }
+  return result;
+}

package/src/tokens.d.ts

@@ -0,0 +1,14 @@
+import { CoinPayClient, SupportedCoinsParams, SupportedCoinsResponse, TokensResponse } from './client.js';
+
+export interface TokenDiscoveryParams extends SupportedCoinsParams {
+  /** API key — required if `client` is not provided */
+  apiKey?: string;
+  /** Existing CoinPayClient instance */
+  client?: CoinPayClient;
+}
+
+/** List checkout-friendly tokens for a business. */
+export function getTokens(params?: TokenDiscoveryParams): Promise<TokensResponse>;
+
+/** List supported payment coins for a business. */
+export function getSupportedCoins(params?: TokenDiscoveryParams): Promise<SupportedCoinsResponse>;