@atumlabs/payment-gateway-client 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.0] - 2026-08-04
+
+> **Read this before upgrading if you script `send-payment`.** Its exit codes now
+> distinguish a settled payment from one still settling and one that failed, where every
+> accepted submission previously exited `0`. See the first entry under Changed.
+>
+> One typed-API change: three fields on `PaymentResponse` are no longer optional. This makes
+> reading a response simpler, not harder — see Changed.
+
+### Added
+- `send-payment --wait` keeps checking a submitted payment until it settles or fails, instead of reporting it as still pending. `--wait-seconds <n>` sets how long (default 60). With `--wait` the JSON on stdout is printed once the wait ends and reports the payment as of the last check — so it carries the settled `status` and the `fulfillment_confirmation`, rather than the `pending` the submit returned. Without `--wait`, output is unchanged. The bound is a client-side convenience: giving up does not affect the payment, and re-submitting the same `request_id` or reading the status endpoint picks up wherever it got to. A settlement that stalls never becomes terminal on its own, so no bound can promise a terminal answer.
+- `send-payment` and `payment-status` now print a one-line outcome summary to stderr saying what the payment's state means for a re-attempt: a pending payment is collected by re-submitting the **same** `request_id`, while a terminally failed one keeps its id and needs a **new** one. The JSON on stdout is unchanged.
+- Documented in `docs/idempotency.md` and the README: what the `409` compares, that deadlines and the signature are exempt from it, `idempotent_replay`, how to read `status`, and that a direct caller may either poll the status endpoint or re-submit.
+
+### Changed
+- **Behaviour change — `send-payment` exit codes.** Previously any accepted submission exited `0`. Now `0` means `completed`, `2` means `pending`, and `3` means `failed`/`cancelled`; `1` continues to mean the payment could not be submitted. Previously a still-settling payment and a terminally failed one both exited `0`, so `send-payment ... && <next step>` ran the next step for a payment that had not settled — including when re-submitting a `request_id` whose payment had already failed. Scripts that treat `0` as "submitted" should treat `0` and `2` as "submitted"; scripts that mean "settled" now get that from `0` alone. `payment-status` is unaffected: as a lookup, its exit code reports whether the lookup worked.
+- `--request-id`'s help text now states the consequence of omitting it: an id is generated, which makes every bare re-run a separate payment rather than a retry.
+- **`PaymentResponse.payment_id`, `.status` and `.idempotent_replay` are now required** in the typed API, matching what the gateway has always sent. They were typed optional, so TypeScript reported them as possibly `undefined` and reading `idempotent_replay` meant writing `=== true` to satisfy the compiler for a value that is always present. Existing code keeps compiling — a narrowed type only removes checks — unless it constructs a `PaymentResponse` itself, as a test fixture might, in which case all three now have to be supplied.
+
+
+
+### Fixed
+- Corrected the idempotency documentation. The 2.1.0 note below said that reusing a `request_id` with different terms returns the original payment and silently drops the new terms. The gateway rejects it with `409` `IDEMPOTENCY_TERMS_MISMATCH`, so an integrator following the old text would neither expect nor handle that error.
+- `IDEMPOTENCY_TERMS_MISMATCH`'s message described the compared terms as "source, destination, or fulfillment_amount", which had become incomplete — `max_source_amount` is compared too. It now names the categories ("accounts, assets, or amounts") rather than enumerating fields, so it stays accurate as the payment schema grows. The docs describe the comparison the same way, and point at the error's own `message` for which category differed.
+
 ## [2.1.0] - 2026-07-31
 
 ### Added

package/README.md

@@ -51,10 +51,39 @@ send-payment [options] <sender> <amount> <sourceAsset> <receiver> <destinationAs
 
 - `-V, --version` - Output the version number
 - `--gateway <url>` - Payment gateway URL (default: testnet)
-- `--request-id <id>` - Idempotency key; seeds the on-chain deposit nonce. Reuse the same id to retry a payment safely. Omitted: a one-shot id is generated and printed (see [Idempotency and retries](#idempotency-and-retries))
+- `--request-id <id>` - Idempotency key; seeds the on-chain deposit nonce. Re-run with the same id to re-attempt one payment. Omitted, an id is generated and printed, which makes every bare re-run a separate payment (see [Idempotency and retries](#idempotency-and-retries))
 - `--request-id-prefix <prefix>` - Prefix for the auto-generated request id (default: `pmt-gw-cli`)
+- `--wait` - After submitting, keep checking until the payment settles or fails instead of reporting it as still pending
+- `--wait-seconds <n>` - How long `--wait` keeps checking (default: `60`). A convenience bound only; giving up does not affect the payment
 - `-h, --help` - Display help
 
+### Exit codes
+
+`send-payment` reports the payment's ending, so `send-payment ... && <next step>`
+runs the next step only for a settled payment:
+
+| Code | Meaning                                                                     |
+| ---- | --------------------------------------------------------------------------- |
+| `0`  | `completed` — settled                                                       |
+| `2`  | `pending` — accepted, no result yet                                          |
+| `3`  | `failed` / `cancelled` — terminal; a fresh attempt needs a new `--request-id` |
+| `1`  | no outcome obtained (rejected, gateway unreachable, bad arguments)            |
+
+On `2`, follow the payment with **`payment-status <payment_id>`** — the id is in the
+output — or use `--wait` to have `send-payment` do it for you. Re-running
+`send-payment` with the same `--request-id` also returns the current state, but it
+rebuilds and re-sends the payment to do so, which is more work than a status
+lookup.
+
+`1` is the case that reverses that order. It means the outcome is **unknown**, not
+that nothing happened: a request that timed out may still have been accepted, and
+you may not have a `payment_id` to look up. Re-run with the same `--request-id`,
+which resolves to the payment if one was created and creates it if not. The id is
+printed on failure for exactly this.
+
+`payment-status` is a lookup, so its exit code reports whether the lookup worked
+(`0`) or not (`1`), never the payment's outcome — read `status` for that.
+
 ### CAIP-19 Asset Format Examples
 
 - **EVM ERC20**: `eip155:42161/erc20:0xaf88d065e77c8cC2239327C5EDb3A432268e5831`
@@ -209,11 +238,34 @@ async function sendPayment() {
       requestBody: paymentRequest
     }) as PaymentResponse;
 
-    console.log('Payment successful!');
+    // A 2xx means the payment was accepted, NOT that it settled. Branch on `status`:
+    // cross-chain settlement can outrun the gateway's synchronous window, so an accepted
+    // payment may still have no result yet. See "Idempotency and retries" below.
     console.log('Payment ID:', response.payment_id);
-    console.log('Source TX:', response.fulfillment_confirmation?.source_tx_hash);
-    console.log('Destination TX:', response.fulfillment_confirmation?.destination_tx_hash);
-    
+    if (response.idempotent_replay) {
+      // This request_id had been used before, so this is the payment your earlier attempt
+      // created. Nothing additional was charged.
+      console.log('Handed back an existing payment');
+    }
+
+    switch (response.status) {
+      case 'completed':
+        console.log('Settled.');
+        console.log('Source TX:', response.fulfillment_confirmation?.source_tx_hash);
+        console.log('Destination TX:', response.fulfillment_confirmation?.destination_tx_hash);
+        break;
+      case 'failed':
+      case 'cancelled':
+        // Terminal, and this request_id stays bound to it. A fresh attempt needs a NEW id.
+        console.error('Failed:', response.error?.code, response.error?.message);
+        break;
+      default:
+        // Still settling. Do not release goods, and do not pay again under a new id.
+        // Follow it with getPaymentStatus(payment_id); re-submitting this same request
+        // also returns the current state, but it re-sends the payment to do so.
+        console.log('Still settling — follow it with getPaymentStatus.');
+    }
+
     return response;
   } catch (error) {
     const gwError = getErrorResponse(error);
@@ -256,6 +308,26 @@ try {
 }
 ```
 
+A thrown error does **not** mean no payment was created — a request that timed out
+may still have been accepted. Treat it as unknown rather than as a failure:
+
+- If you already hold the `payment_id` from an earlier attempt, read
+  `getPaymentStatus` — the cheapest way to find out what happened.
+- If you do not, re-submit the same `request_id`. It resolves to the payment if one
+  was created and creates it if not, which is the only recovery that works without
+  an id.
+
+One code is worth handling by name:
+
+```typescript
+const gwError = getErrorResponse(error);
+if (gwError?.code === 'IDEMPOTENCY_TERMS_MISMATCH') {
+  // 409 — this request_id already identifies a payment with different economics.
+  // Re-submitting cannot amend that payment; a genuinely different one needs a new
+  // request_id. See "Idempotency and retries".
+}
+```
+
 ### Asset Identifiers
 
 Assets are identified using the [CAIP-19](https://chainagnostic.org/CAIPs/caip-19) format:
@@ -273,15 +345,23 @@ with one payment, not two — and you get the same answer each time.
   (`preparePaymentRequest`), and it is the only thing you manage: the SDK derives
   the on-chain deposit nonce deterministically from it, so retries line up on
   their own. Reuse the same `request_id` to retry safely.
-- On the CLI, `--request-id` is optional; when omitted a one-shot id is generated
-  and printed, so you can re-run with `--request-id <id>` to retry the same
-  payment.
+- On the CLI, `--request-id` is optional; when omitted an id is generated and
+  printed, so you can re-run with `--request-id <id>` to re-attempt the same
+  payment. A bare re-run, with no `--request-id`, is a **separate** payment.
 - A genuinely new payment needs a **new** `request_id`. Reusing one with different
-  terms (a corrected amount, a different token) returns the original payment
-  rather than an error, so the new terms are silently dropped.
+  economics (a corrected amount, a different token) is rejected with `409`
+  `IDEMPOTENCY_TERMS_MISMATCH` — one id identifies one payment.
+- Deadlines and the signature are exempt, so a re-submission of the original
+  bytes is fine even though its deadlines have expired by then.
+- `idempotent_replay` on the response tells you whether you were handed a payment
+  that already existed.
+- `pending` is not success. It means accepted and still settling: re-submit the
+  same `request_id` to collect the result. A `failed` payment is terminal and
+  keeps its id, so recovering from one needs a new id.
 
 See [docs/idempotency.md](docs/idempotency.md) for the full model: the two
-guarantees and the per-chain differences (EVM/Tron vs Solana).
+guarantees, when the `409` applies, how to read the outcome, and the per-chain
+differences (EVM/Tron vs Solana).
 
 ## What is in the package
 

package/dist/cli/payment-status.js

@@ -249,12 +249,14 @@ var require_utils = __commonJS({
   "../schemas/declarations/PaymentRequest/v1/bindings/typescript/sender-auth/dist/utils.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    exports2.SOLANA_REPLAY_SLOTS = exports2.PERMIT_NONCE_DOMAIN = exports2.REPLAY_HORIZON_SECS = void 0;
+    exports2.REQUEST_ID_DOMAIN = exports2.SOLANA_REPLAY_SLOTS = exports2.PERMIT_NONCE_DOMAIN = exports2.REPLAY_HORIZON_SECS = void 0;
     exports2.resolvePermitDeadline = resolvePermitDeadline;
     exports2.generatePermitNonce = generatePermitNonce;
     exports2.resolvePermitNonce = resolvePermitNonce;
+    exports2.canonicalDepositor = canonicalDepositor;
     exports2.deterministicPermitNonce = deterministicPermitNonce2;
     exports2.deterministicSolanaNonce = deterministicSolanaNonce2;
+    exports2.deterministicRequestId = deterministicRequestId;
     exports2.sameAddress = sameAddress;
     exports2.assertKeyMatchesSender = assertKeyMatchesSender2;
     exports2.assertToken = assertToken;
@@ -299,6 +301,20 @@ var require_utils = __commonJS({
       const bucket = (seed >> 8n) % (1n << SOLANA_BUCKET_BITS);
       return bucket << 32n | slot;
     }
+    exports2.REQUEST_ID_DOMAIN = "atum-request:v1:";
+    function deterministicRequestId(params) {
+      if (!params.anchor) {
+        throw new Error("sender_auth: a per-intent anchor is required to derive a deterministic request_id (a random one would silently break idempotency and let a retry double-charge)");
+      }
+      if (!params.account) {
+        throw new Error("sender_auth: account is required to derive a deterministic request_id");
+      }
+      if (!/^[A-Za-z0-9_-]*$/.test(params.prefix)) {
+        throw new Error(`sender_auth: request_id prefix must contain only letters, digits, '_' or '-' (got ${JSON.stringify(params.prefix)})`);
+      }
+      const digest = (0, ethers_1.keccak256)((0, ethers_1.toUtf8Bytes)(`${exports2.REQUEST_ID_DOMAIN}${params.anchor}:${canonicalDepositor(params.account)}`));
+      return `${params.prefix}${digest.slice(2, 26)}`;
+    }
     function sameAddress(a, b) {
       if (a.startsWith("0x") && b.startsWith("0x")) {
         return a.toLowerCase() === b.toLowerCase();
@@ -890,7 +906,7 @@ var require_evm = __commonJS({
     exports2.evmAdapter = {
       async buildAuthMessage({ sourceAsset, maxSourceAmount, sourceDefaults, deadline, nonce }) {
         if (nonce === void 0) {
-          throw new Error("sender_auth: buildAuthMessage requires an explicit nonce \u2014 derive it deterministically from a stable request id (e.g. the challenge id) so retries reproduce the same permit; pass generatePermitNonce() only for genuinely one-shot builds");
+          throw new Error("sender_auth: buildAuthMessage requires an explicit nonce \u2014 derive it deterministically from a stable request id (e.g. an order id) so retries reproduce the same permit; pass generatePermitNonce() only for genuinely one-shot builds");
         }
         if (deadline === void 0) {
           throw new Error("sender_auth: buildAuthMessage requires an explicit permit deadline (absolute Unix seconds) \u2014 the low-level builder does not default it; derive it from the payment's fulfillment/settlement deadline in the calling layer (pgc/mppx)");
@@ -918,6 +934,10 @@ var require_evm = __commonJS({
           throw new Error("EVM adapter sign(): signed_messages[i].message_prehash is required");
         }
         const prehash = JSON.parse(signedMessage.message_prehash);
+        const prehashDigest = (0, evm_escrow_encoding_1.hashPermitWitnessTransferFrom)(prehash);
+        if (prehashDigest.toLowerCase() !== signedMessage.message.toLowerCase()) {
+          throw new Error(`EVM adapter sign(): message_prehash implies digest ${prehashDigest} but message is ${signedMessage.message}`);
+        }
         const wallet = new ethers_1.Wallet(privateKey);
         return wallet.signTypedData(prehash.domain, prehash.types, prehash.message);
       },
@@ -1004,7 +1024,7 @@ var require_tron = __commonJS({
     exports2.tronAdapter = {
       async buildAuthMessage({ sourceAsset, maxSourceAmount, sourceDefaults, deadline, nonce }) {
         if (nonce === void 0) {
-          throw new Error("sender_auth: buildAuthMessage requires an explicit nonce \u2014 derive it deterministically from a stable request id (e.g. the challenge id) so retries reproduce the same permit; pass generatePermitNonce() only for genuinely one-shot builds");
+          throw new Error("sender_auth: buildAuthMessage requires an explicit nonce \u2014 derive it deterministically from a stable request id (e.g. an order id) so retries reproduce the same permit; pass generatePermitNonce() only for genuinely one-shot builds");
         }
         if (deadline === void 0) {
           throw new Error("sender_auth: buildAuthMessage requires an explicit permit deadline (absolute Unix seconds) \u2014 the low-level builder does not default it; derive it from the payment's fulfillment/settlement deadline in the calling layer (pgc/mppx)");
@@ -1027,9 +1047,19 @@ var require_tron = __commonJS({
         const messageHash = (0, tvm_escrow_encoding_1.hashTvmPermitWitnessTransferFrom)(messagePrehash);
         return { messageScheme: "EVM_PERMIT2", messageHash, messagePrehash: JSON.stringify(messagePrehash) };
       },
+      // Signs the TIP-712 typed data, not the bare digest, so a signer can inspect the fields it is
+      // authorizing (Turnkey policies read `eth.eip_712.message[...]`).
       async sign(signedMessage, privateKey) {
+        if (!signedMessage.message_prehash) {
+          throw new Error("Tron adapter sign(): signed_messages[i].message_prehash is required");
+        }
+        const prehash = JSON.parse(signedMessage.message_prehash);
+        const prehashDigest = (0, tvm_escrow_encoding_1.hashTvmPermitWitnessTransferFrom)(prehash);
+        if (prehashDigest.toLowerCase() !== signedMessage.message.toLowerCase()) {
+          throw new Error(`Tron adapter sign(): message_prehash implies digest ${prehashDigest} but message is ${signedMessage.message}`);
+        }
         const wallet = new ethers_1.Wallet(privateKey.startsWith("0x") ? privateKey : "0x" + privateKey);
-        return wallet.signingKey.sign(signedMessage.message).serialized;
+        return wallet.signTypedData(prehash.domain, prehash.types, prehash.message);
       },
       recoverSigner(signed, source) {
         let recovered;
@@ -2867,8 +2897,26 @@ var PaymentsService = class {
    * 2. Find optimal settlement routes across chains/assets
    * 3. Secure funds in escrow
    * 4. Coordinate with settlement agents for execution
-   * 5. Return a real-time result if processing completes within 30 seconds,
-   * otherwise return a payment ID for status polling
+   * 5. Return a real-time result if settlement completes inside the synchronous window,
+   * otherwise return a payment ID and status for polling
+   *
+   * **Idempotency.** `request_id` is the idempotency key, scoped to the source account
+   * and originator. Submitting the same `request_id` again returns the ORIGINAL payment
+   * instead of charging a second time, so a client whose request timed out or failed
+   * in transit can safely re-submit.
+   *
+   * Because a re-submission must be admissible on its own, some fields legitimately
+   * differ between attempts and are excluded from the comparison: `quote_deadline` and
+   * `fulfillment_deadline` (both must be in the future, so a later attempt has to move
+   * them), and the `sender_auth` signature they are signed into.
+   *
+   * What must NOT differ is the payment's economics — source account and asset,
+   * destination accounts and assets, `fulfillment_amount`, and `max_source_amount` (the
+   * payer's own risk cap; lowering it on a retry describes a different payment, not the
+   * same one with less headroom). Re-using one `request_id` for a genuinely different
+   * payment is a client bug that would otherwise be silently collapsed onto the first
+   * payment, so it is rejected with `409` and `IDEMPOTENCY_TERMS_MISMATCH`. Use a
+   * distinct `request_id` per payment.
    *
    * @param data The data for the request.
    * @param data.requestBody
@@ -2885,6 +2933,11 @@ var PaymentsService = class {
         400: "Invalid request",
         401: "Signature or sender authorization could not be verified",
         403: "Payment declined during counterparty authorization",
+        409: `The \`request_id\` has already been used for a payment with different economics
+(\`IDEMPOTENCY_TERMS_MISMATCH\`). Re-submitting one \`request_id\` is how a retry is
+made safe, so it must identify one payment; use a distinct \`request_id\` per
+payment.
+`,
         413: "Payment request too large to process",
         500: "Internal server error",
         503: "A dependency is temporarily unavailable"
@@ -3704,7 +3757,7 @@ var PaymentGatewayClient2 = class extends PaymentGatewayClient {
 };
 
 // src/version.ts
-var PACKAGE_VERSION = true ? "2.1.0" : "0.0.0-dev";
+var PACKAGE_VERSION = true ? "2.2.0" : "0.0.0-dev";
 
 // src/cli/load-env.ts
 var import_dotenv = require("dotenv");
@@ -3712,6 +3765,34 @@ function loadCliEnv() {
   (0, import_dotenv.config)({ override: false, quiet: true });
 }
 
+// src/cli/payment-outcome.ts
+var EXIT_COMPLETED = 0;
+var EXIT_PENDING = 2;
+var EXIT_TERMINAL_FAILURE = 3;
+function describePaymentOutcome(input) {
+  const { status, paymentId, requestId, idempotentReplay, errorCode } = input;
+  const payment = paymentId ? `payment ${paymentId}` : "the payment";
+  const replay = idempotentReplay ? " This is the payment your earlier attempt created \u2014 nothing additional was charged." : "";
+  if (status === "completed") {
+    return {
+      exitCode: EXIT_COMPLETED,
+      summary: `completed: ${payment} settled.${replay}`
+    };
+  }
+  if (status === "failed" || status === "cancelled") {
+    const reason = errorCode ? ` (${errorCode})` : "";
+    return {
+      exitCode: EXIT_TERMINAL_FAILURE,
+      summary: `${status}: ${payment} ended without settling${reason}. This is final \u2014 re-submitting ${requestId ? `request id ${requestId}` : "the same request id"} returns this same failed payment, so a fresh attempt needs a NEW request id.`
+    };
+  }
+  const resubmit = requestId ? `request id ${requestId}` : "the same request id";
+  return {
+    exitCode: EXIT_PENDING,
+    summary: `pending: ${payment} was accepted and is still settling.${replay} To collect the result, keep checking its status, or re-submit ${resubmit}. Do not start a new payment under a different request id \u2014 that would pay twice.`
+  };
+}
+
 // src/cli/payment-status.ts
 loadCliEnv();
 var program = new import_commander.Command();
@@ -3722,11 +3803,22 @@ Example:
 Status values: pending | completed | failed | cancelled
 
 Output:
-  Response JSON  -> stdout (for parsing/automation, e.g. | jq)`).action(async (paymentId, options) => {
+  Response JSON     -> stdout (for parsing/automation, e.g. | jq)
+  What it means     -> stderr
+
+Exit code reports whether the lookup worked (0) or not (1), not the payment's
+outcome \u2014 read \`status\` for that, or use send-payment's exit code.`).action(async (paymentId, options) => {
   try {
     const client = new PaymentGatewayClient2({ BASE: options.gateway });
     const response = await client.payments.getPaymentStatus({ paymentId });
     console.log(JSON.stringify(response, null, 2));
+    console.error(
+      describePaymentOutcome({
+        status: response.status,
+        paymentId: response.payment_id ?? paymentId,
+        errorCode: response.error?.code
+      }).summary
+    );
     process.exit(0);
   } catch (error) {
     if (error instanceof ApiError && error.body) {

package/dist/cli/quote-status.js

@@ -249,12 +249,14 @@ var require_utils = __commonJS({
   "../schemas/declarations/PaymentRequest/v1/bindings/typescript/sender-auth/dist/utils.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    exports2.SOLANA_REPLAY_SLOTS = exports2.PERMIT_NONCE_DOMAIN = exports2.REPLAY_HORIZON_SECS = void 0;
+    exports2.REQUEST_ID_DOMAIN = exports2.SOLANA_REPLAY_SLOTS = exports2.PERMIT_NONCE_DOMAIN = exports2.REPLAY_HORIZON_SECS = void 0;
     exports2.resolvePermitDeadline = resolvePermitDeadline;
     exports2.generatePermitNonce = generatePermitNonce;
     exports2.resolvePermitNonce = resolvePermitNonce;
+    exports2.canonicalDepositor = canonicalDepositor;
     exports2.deterministicPermitNonce = deterministicPermitNonce2;
     exports2.deterministicSolanaNonce = deterministicSolanaNonce2;
+    exports2.deterministicRequestId = deterministicRequestId;
     exports2.sameAddress = sameAddress;
     exports2.assertKeyMatchesSender = assertKeyMatchesSender2;
     exports2.assertToken = assertToken;
@@ -299,6 +301,20 @@ var require_utils = __commonJS({
       const bucket = (seed >> 8n) % (1n << SOLANA_BUCKET_BITS);
       return bucket << 32n | slot;
     }
+    exports2.REQUEST_ID_DOMAIN = "atum-request:v1:";
+    function deterministicRequestId(params) {
+      if (!params.anchor) {
+        throw new Error("sender_auth: a per-intent anchor is required to derive a deterministic request_id (a random one would silently break idempotency and let a retry double-charge)");
+      }
+      if (!params.account) {
+        throw new Error("sender_auth: account is required to derive a deterministic request_id");
+      }
+      if (!/^[A-Za-z0-9_-]*$/.test(params.prefix)) {
+        throw new Error(`sender_auth: request_id prefix must contain only letters, digits, '_' or '-' (got ${JSON.stringify(params.prefix)})`);
+      }
+      const digest = (0, ethers_1.keccak256)((0, ethers_1.toUtf8Bytes)(`${exports2.REQUEST_ID_DOMAIN}${params.anchor}:${canonicalDepositor(params.account)}`));
+      return `${params.prefix}${digest.slice(2, 26)}`;
+    }
     function sameAddress(a, b) {
       if (a.startsWith("0x") && b.startsWith("0x")) {
         return a.toLowerCase() === b.toLowerCase();
@@ -890,7 +906,7 @@ var require_evm = __commonJS({
     exports2.evmAdapter = {
       async buildAuthMessage({ sourceAsset, maxSourceAmount, sourceDefaults, deadline, nonce }) {
         if (nonce === void 0) {
-          throw new Error("sender_auth: buildAuthMessage requires an explicit nonce \u2014 derive it deterministically from a stable request id (e.g. the challenge id) so retries reproduce the same permit; pass generatePermitNonce() only for genuinely one-shot builds");
+          throw new Error("sender_auth: buildAuthMessage requires an explicit nonce \u2014 derive it deterministically from a stable request id (e.g. an order id) so retries reproduce the same permit; pass generatePermitNonce() only for genuinely one-shot builds");
         }
         if (deadline === void 0) {
           throw new Error("sender_auth: buildAuthMessage requires an explicit permit deadline (absolute Unix seconds) \u2014 the low-level builder does not default it; derive it from the payment's fulfillment/settlement deadline in the calling layer (pgc/mppx)");
@@ -918,6 +934,10 @@ var require_evm = __commonJS({
           throw new Error("EVM adapter sign(): signed_messages[i].message_prehash is required");
         }
         const prehash = JSON.parse(signedMessage.message_prehash);
+        const prehashDigest = (0, evm_escrow_encoding_1.hashPermitWitnessTransferFrom)(prehash);
+        if (prehashDigest.toLowerCase() !== signedMessage.message.toLowerCase()) {
+          throw new Error(`EVM adapter sign(): message_prehash implies digest ${prehashDigest} but message is ${signedMessage.message}`);
+        }
         const wallet = new ethers_1.Wallet(privateKey);
         return wallet.signTypedData(prehash.domain, prehash.types, prehash.message);
       },
@@ -1004,7 +1024,7 @@ var require_tron = __commonJS({
     exports2.tronAdapter = {
       async buildAuthMessage({ sourceAsset, maxSourceAmount, sourceDefaults, deadline, nonce }) {
         if (nonce === void 0) {
-          throw new Error("sender_auth: buildAuthMessage requires an explicit nonce \u2014 derive it deterministically from a stable request id (e.g. the challenge id) so retries reproduce the same permit; pass generatePermitNonce() only for genuinely one-shot builds");
+          throw new Error("sender_auth: buildAuthMessage requires an explicit nonce \u2014 derive it deterministically from a stable request id (e.g. an order id) so retries reproduce the same permit; pass generatePermitNonce() only for genuinely one-shot builds");
         }
         if (deadline === void 0) {
           throw new Error("sender_auth: buildAuthMessage requires an explicit permit deadline (absolute Unix seconds) \u2014 the low-level builder does not default it; derive it from the payment's fulfillment/settlement deadline in the calling layer (pgc/mppx)");
@@ -1027,9 +1047,19 @@ var require_tron = __commonJS({
         const messageHash = (0, tvm_escrow_encoding_1.hashTvmPermitWitnessTransferFrom)(messagePrehash);
         return { messageScheme: "EVM_PERMIT2", messageHash, messagePrehash: JSON.stringify(messagePrehash) };
       },
+      // Signs the TIP-712 typed data, not the bare digest, so a signer can inspect the fields it is
+      // authorizing (Turnkey policies read `eth.eip_712.message[...]`).
       async sign(signedMessage, privateKey) {
+        if (!signedMessage.message_prehash) {
+          throw new Error("Tron adapter sign(): signed_messages[i].message_prehash is required");
+        }
+        const prehash = JSON.parse(signedMessage.message_prehash);
+        const prehashDigest = (0, tvm_escrow_encoding_1.hashTvmPermitWitnessTransferFrom)(prehash);
+        if (prehashDigest.toLowerCase() !== signedMessage.message.toLowerCase()) {
+          throw new Error(`Tron adapter sign(): message_prehash implies digest ${prehashDigest} but message is ${signedMessage.message}`);
+        }
         const wallet = new ethers_1.Wallet(privateKey.startsWith("0x") ? privateKey : "0x" + privateKey);
-        return wallet.signingKey.sign(signedMessage.message).serialized;
+        return wallet.signTypedData(prehash.domain, prehash.types, prehash.message);
       },
       recoverSigner(signed, source) {
         let recovered;
@@ -2867,8 +2897,26 @@ var PaymentsService = class {
    * 2. Find optimal settlement routes across chains/assets
    * 3. Secure funds in escrow
    * 4. Coordinate with settlement agents for execution
-   * 5. Return a real-time result if processing completes within 30 seconds,
-   * otherwise return a payment ID for status polling
+   * 5. Return a real-time result if settlement completes inside the synchronous window,
+   * otherwise return a payment ID and status for polling
+   *
+   * **Idempotency.** `request_id` is the idempotency key, scoped to the source account
+   * and originator. Submitting the same `request_id` again returns the ORIGINAL payment
+   * instead of charging a second time, so a client whose request timed out or failed
+   * in transit can safely re-submit.
+   *
+   * Because a re-submission must be admissible on its own, some fields legitimately
+   * differ between attempts and are excluded from the comparison: `quote_deadline` and
+   * `fulfillment_deadline` (both must be in the future, so a later attempt has to move
+   * them), and the `sender_auth` signature they are signed into.
+   *
+   * What must NOT differ is the payment's economics — source account and asset,
+   * destination accounts and assets, `fulfillment_amount`, and `max_source_amount` (the
+   * payer's own risk cap; lowering it on a retry describes a different payment, not the
+   * same one with less headroom). Re-using one `request_id` for a genuinely different
+   * payment is a client bug that would otherwise be silently collapsed onto the first
+   * payment, so it is rejected with `409` and `IDEMPOTENCY_TERMS_MISMATCH`. Use a
+   * distinct `request_id` per payment.
    *
    * @param data The data for the request.
    * @param data.requestBody
@@ -2885,6 +2933,11 @@ var PaymentsService = class {
         400: "Invalid request",
         401: "Signature or sender authorization could not be verified",
         403: "Payment declined during counterparty authorization",
+        409: `The \`request_id\` has already been used for a payment with different economics
+(\`IDEMPOTENCY_TERMS_MISMATCH\`). Re-submitting one \`request_id\` is how a retry is
+made safe, so it must identify one payment; use a distinct \`request_id\` per
+payment.
+`,
         413: "Payment request too large to process",
         500: "Internal server error",
         503: "A dependency is temporarily unavailable"
@@ -3704,7 +3757,7 @@ var PaymentGatewayClient2 = class extends PaymentGatewayClient {
 };
 
 // src/version.ts
-var PACKAGE_VERSION = true ? "2.1.0" : "0.0.0-dev";
+var PACKAGE_VERSION = true ? "2.2.0" : "0.0.0-dev";
 
 // src/cli/load-env.ts
 var import_dotenv = require("dotenv");

package/dist/cli/request-quote.js

@@ -249,12 +249,14 @@ var require_utils = __commonJS({
   "../schemas/declarations/PaymentRequest/v1/bindings/typescript/sender-auth/dist/utils.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    exports2.SOLANA_REPLAY_SLOTS = exports2.PERMIT_NONCE_DOMAIN = exports2.REPLAY_HORIZON_SECS = void 0;
+    exports2.REQUEST_ID_DOMAIN = exports2.SOLANA_REPLAY_SLOTS = exports2.PERMIT_NONCE_DOMAIN = exports2.REPLAY_HORIZON_SECS = void 0;
     exports2.resolvePermitDeadline = resolvePermitDeadline;
     exports2.generatePermitNonce = generatePermitNonce;
     exports2.resolvePermitNonce = resolvePermitNonce;
+    exports2.canonicalDepositor = canonicalDepositor;
     exports2.deterministicPermitNonce = deterministicPermitNonce2;
     exports2.deterministicSolanaNonce = deterministicSolanaNonce2;
+    exports2.deterministicRequestId = deterministicRequestId;
     exports2.sameAddress = sameAddress;
     exports2.assertKeyMatchesSender = assertKeyMatchesSender2;
     exports2.assertToken = assertToken;
@@ -299,6 +301,20 @@ var require_utils = __commonJS({
       const bucket = (seed >> 8n) % (1n << SOLANA_BUCKET_BITS);
       return bucket << 32n | slot;
     }
+    exports2.REQUEST_ID_DOMAIN = "atum-request:v1:";
+    function deterministicRequestId(params) {
+      if (!params.anchor) {
+        throw new Error("sender_auth: a per-intent anchor is required to derive a deterministic request_id (a random one would silently break idempotency and let a retry double-charge)");
+      }
+      if (!params.account) {
+        throw new Error("sender_auth: account is required to derive a deterministic request_id");
+      }
+      if (!/^[A-Za-z0-9_-]*$/.test(params.prefix)) {
+        throw new Error(`sender_auth: request_id prefix must contain only letters, digits, '_' or '-' (got ${JSON.stringify(params.prefix)})`);
+      }
+      const digest = (0, ethers_1.keccak256)((0, ethers_1.toUtf8Bytes)(`${exports2.REQUEST_ID_DOMAIN}${params.anchor}:${canonicalDepositor(params.account)}`));
+      return `${params.prefix}${digest.slice(2, 26)}`;
+    }
     function sameAddress(a, b) {
       if (a.startsWith("0x") && b.startsWith("0x")) {
         return a.toLowerCase() === b.toLowerCase();
@@ -890,7 +906,7 @@ var require_evm = __commonJS({
     exports2.evmAdapter = {
       async buildAuthMessage({ sourceAsset, maxSourceAmount, sourceDefaults, deadline, nonce }) {
         if (nonce === void 0) {
-          throw new Error("sender_auth: buildAuthMessage requires an explicit nonce \u2014 derive it deterministically from a stable request id (e.g. the challenge id) so retries reproduce the same permit; pass generatePermitNonce() only for genuinely one-shot builds");
+          throw new Error("sender_auth: buildAuthMessage requires an explicit nonce \u2014 derive it deterministically from a stable request id (e.g. an order id) so retries reproduce the same permit; pass generatePermitNonce() only for genuinely one-shot builds");
         }
         if (deadline === void 0) {
           throw new Error("sender_auth: buildAuthMessage requires an explicit permit deadline (absolute Unix seconds) \u2014 the low-level builder does not default it; derive it from the payment's fulfillment/settlement deadline in the calling layer (pgc/mppx)");
@@ -918,6 +934,10 @@ var require_evm = __commonJS({
           throw new Error("EVM adapter sign(): signed_messages[i].message_prehash is required");
         }
         const prehash = JSON.parse(signedMessage.message_prehash);
+        const prehashDigest = (0, evm_escrow_encoding_1.hashPermitWitnessTransferFrom)(prehash);
+        if (prehashDigest.toLowerCase() !== signedMessage.message.toLowerCase()) {
+          throw new Error(`EVM adapter sign(): message_prehash implies digest ${prehashDigest} but message is ${signedMessage.message}`);
+        }
         const wallet = new ethers_1.Wallet(privateKey);
         return wallet.signTypedData(prehash.domain, prehash.types, prehash.message);
       },
@@ -1004,7 +1024,7 @@ var require_tron = __commonJS({
     exports2.tronAdapter = {
       async buildAuthMessage({ sourceAsset, maxSourceAmount, sourceDefaults, deadline, nonce }) {
         if (nonce === void 0) {
-          throw new Error("sender_auth: buildAuthMessage requires an explicit nonce \u2014 derive it deterministically from a stable request id (e.g. the challenge id) so retries reproduce the same permit; pass generatePermitNonce() only for genuinely one-shot builds");
+          throw new Error("sender_auth: buildAuthMessage requires an explicit nonce \u2014 derive it deterministically from a stable request id (e.g. an order id) so retries reproduce the same permit; pass generatePermitNonce() only for genuinely one-shot builds");
         }
         if (deadline === void 0) {
           throw new Error("sender_auth: buildAuthMessage requires an explicit permit deadline (absolute Unix seconds) \u2014 the low-level builder does not default it; derive it from the payment's fulfillment/settlement deadline in the calling layer (pgc/mppx)");
@@ -1027,9 +1047,19 @@ var require_tron = __commonJS({
         const messageHash = (0, tvm_escrow_encoding_1.hashTvmPermitWitnessTransferFrom)(messagePrehash);
         return { messageScheme: "EVM_PERMIT2", messageHash, messagePrehash: JSON.stringify(messagePrehash) };
       },
+      // Signs the TIP-712 typed data, not the bare digest, so a signer can inspect the fields it is
+      // authorizing (Turnkey policies read `eth.eip_712.message[...]`).
       async sign(signedMessage, privateKey) {
+        if (!signedMessage.message_prehash) {
+          throw new Error("Tron adapter sign(): signed_messages[i].message_prehash is required");
+        }
+        const prehash = JSON.parse(signedMessage.message_prehash);
+        const prehashDigest = (0, tvm_escrow_encoding_1.hashTvmPermitWitnessTransferFrom)(prehash);
+        if (prehashDigest.toLowerCase() !== signedMessage.message.toLowerCase()) {
+          throw new Error(`Tron adapter sign(): message_prehash implies digest ${prehashDigest} but message is ${signedMessage.message}`);
+        }
         const wallet = new ethers_1.Wallet(privateKey.startsWith("0x") ? privateKey : "0x" + privateKey);
-        return wallet.signingKey.sign(signedMessage.message).serialized;
+        return wallet.signTypedData(prehash.domain, prehash.types, prehash.message);
       },
       recoverSigner(signed, source) {
         let recovered;
@@ -2867,8 +2897,26 @@ var PaymentsService = class {
    * 2. Find optimal settlement routes across chains/assets
    * 3. Secure funds in escrow
    * 4. Coordinate with settlement agents for execution
-   * 5. Return a real-time result if processing completes within 30 seconds,
-   * otherwise return a payment ID for status polling
+   * 5. Return a real-time result if settlement completes inside the synchronous window,
+   * otherwise return a payment ID and status for polling
+   *
+   * **Idempotency.** `request_id` is the idempotency key, scoped to the source account
+   * and originator. Submitting the same `request_id` again returns the ORIGINAL payment
+   * instead of charging a second time, so a client whose request timed out or failed
+   * in transit can safely re-submit.
+   *
+   * Because a re-submission must be admissible on its own, some fields legitimately
+   * differ between attempts and are excluded from the comparison: `quote_deadline` and
+   * `fulfillment_deadline` (both must be in the future, so a later attempt has to move
+   * them), and the `sender_auth` signature they are signed into.
+   *
+   * What must NOT differ is the payment's economics — source account and asset,
+   * destination accounts and assets, `fulfillment_amount`, and `max_source_amount` (the
+   * payer's own risk cap; lowering it on a retry describes a different payment, not the
+   * same one with less headroom). Re-using one `request_id` for a genuinely different
+   * payment is a client bug that would otherwise be silently collapsed onto the first
+   * payment, so it is rejected with `409` and `IDEMPOTENCY_TERMS_MISMATCH`. Use a
+   * distinct `request_id` per payment.
    *
    * @param data The data for the request.
    * @param data.requestBody
@@ -2885,6 +2933,11 @@ var PaymentsService = class {
         400: "Invalid request",
         401: "Signature or sender authorization could not be verified",
         403: "Payment declined during counterparty authorization",
+        409: `The \`request_id\` has already been used for a payment with different economics
+(\`IDEMPOTENCY_TERMS_MISMATCH\`). Re-submitting one \`request_id\` is how a retry is
+made safe, so it must identify one payment; use a distinct \`request_id\` per
+payment.
+`,
         413: "Payment request too large to process",
         500: "Internal server error",
         503: "A dependency is temporarily unavailable"
@@ -3714,7 +3767,7 @@ function parseSeconds(optionName) {
 }
 
 // src/version.ts
-var PACKAGE_VERSION = true ? "2.1.0" : "0.0.0-dev";
+var PACKAGE_VERSION = true ? "2.2.0" : "0.0.0-dev";
 
 // src/cli/load-env.ts
 var import_dotenv = require("dotenv");