Clarify exact-input strict deposit address overpayment behavior

[ted-palmer]

No description provided.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
unevenlabs	🟢 Ready	View Preview	Aug 31, 2026, 8:57 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[github-actions]

Claude finished @ted-palmer's task in 2m 3s —— View job

---

Review: Clarify exact-input strict deposit address overpayment behavior

• Read PR diff
• Check for other overpayment/strict-address statements that may now be inconsistent
• Validate against AGENTS.md style rules
• Post review

The correction itself looks right, and editing references/api/changelog.mdx (the source) rather than the generated changelog.mdx is the correct move per AGENTS.md §4.6 — the hourly sync will regenerate the published page. A few things to consider before merging.

---

1. EXPECTED_OUTPUT is now an undocumented case

features/deposit-addresses.mdx:900-901

The old bullet covered every trade type in one statement. Splitting it into EXACT_INPUT / EXACT_OUTPUT leaves the third documented trade type unanswered — EXPECTED_OUTPUT is listed as valid in the same file's parameter table:

features/deposit-addresses.mdx:28
| `tradeType` | string | `EXACT_INPUT` or `EXPECTED_OUTPUT` for open deposit addresses. `EXACT_OUTPUT` is supported only with a strict deposit address (`strict: true`) … |

That line scopes EXACT_OUTPUT to strict but never says which types strict rejects, so a reader pairing strict: true with EXPECTED_OUTPUT now has no answer. Either fold it into the EXACT_INPUT bullet (if it behaves the same) or state explicitly that strict addresses only accept EXACT_INPUT / EXACT_OUTPUT. Same applies to the changelog sentence. Fix this →

2. The new EXACT_INPUT behavior undercuts how strict addresses are positioned

features/deposit-addresses.mdx:51-55

Strict deposit addresses are bound to the original order and should be treated as predictable payment instructions.
… Best for: integrations that need predictable behavior and explicit refund handling (e.g., payment processors).

With EXACT_INPUT, an overpayment now silently delivers more than the invoiced amount to the recipient, with no refund leg — which is exactly the reconciliation edge case that solutions/commerce-and-payments.mdx:57 sells EXACT_OUTPUT as eliminating. Since payment processors are called out as the target audience for strict addresses, worth a one-liner in Strict Deposit Addresses or Recommended Setup (:969-971) pointing payment flows at EXACT_OUTPUT. This is the practical takeaway of the change and currently it's only inferable from a bullet 850 lines down. Fix this →

3. Comparison table cell is now doing prose's job

features/deposit-addresses.mdx:66

AGENTS.md §2.7: "Keep cell descriptions concise; move long explanations into prose below the table." The Strict cell is now ~200 characters carrying the full two-branch explanation, and it duplicates :900-901 verbatim in substance — so this rule already has two places to update, which is what produced the drift being fixed here. Suggest:

| Amount mismatch | Usually requotes for actual amount; too-small deposits may refund | Underpayments refund; exact payments fill; overpayment handling depends on trade type — see [Strict Addresses](#strict-addresses) |

4. Wording on the new bullet

features/deposit-addresses.mdx:900

Overpayment (EXACT_INPUT) — The full deposited amount is filled. The excess is not refunded — the fill scales up to cover everything that was deposited.

An amount isn't filled — an order is. The two sentences also restate each other, and the bolded **not** reads as emphasis rather than the parameter/value emphasis §2.9 reserves bold for. Something tighter that parallels the EXACT_OUTPUT bullet below it:

- **Overpayment (`EXACT_INPUT`)** — The fill scales up to the full deposited amount. Nothing is refunded to `refundTo`.

5. Rewriting a dated changelog entry vs. adding a new one

references/api/changelog.mdx:155-157

The 2026-05-07 entry is being restated to say the change was EXACT_OUTPUT-only. If the 2026-05-07 release was always scoped that way and the entry simply overstated it, an in-place correction is right. If the scope actually changed since, a new dated entry is the more honest record — integrators who read and acted on the original wording won't re-read a nine-month-old entry. Worth confirming which case this is; a one-line note in the PR description would help the next reader.

Minor: the entry paragraph is now four sentences (§2.10 caps at 2–3).

---

Nothing here blocks merge — #1 is the one I'd want resolved, since it turns a previously complete statement into a partial one. Note the generated changelog.mdx:539 still carries the old wording; that's expected and resolves when the hourly sync PR merges.
· branch ted/int2-1284-update-deposit-address-documentation-for-exact-input

[greptile-apps]

Greptile Summary

This change updates strict deposit-address overpayment guidance and narrows the May 7 changelog entry to exact-output requests. Safe live quote requests confirmed that both strict EXACT_INPUT and EXACT_OUTPUT modes are accepted, but RelayKit’s generated API contract specifies quoted-fill plus excess-refund handling for strict overpayments without a trade-type exception. The EXACT_INPUT no-refund guidance in the deposit-address guide and changelog should be corrected before merge.

Confidence Score: 4/5

Not safe to merge until the strict EXACT_INPUT overpayment documentation matches the published API contract.

A safe live quote check for both trade types and the current generated RelayKit schema consistently contradict the newly documented EXACT_INPUT exception.

Files Needing Attention: features/deposit-addresses.mdx and references/api/changelog.mdx need their trade-type-specific strict-overpayment statements corrected.

T-Rex Logs

What T-Rex did

• T-Rex generated a finding-comment proof for the posted P1 finding and attached the strict-overpayment live quote validation script along with review-relevant logs.
• T-Rex generated a second finding-comment proof for a posted P1 finding, with no artifacts attached.
• T-Rex provided a general-contract-validation-proof showing the before-and-after capture of strict-overpayment rules, including the base documentation rule, the successful after-capture live quotes, and the RelayKit schema that refunds excess with no exact-input exception; the included source command performs only quote requests.

_{Ran code and verified through T-Rex}

Comments Outside Diff (1)

1. General comment

   Strict EXACT_INPUT overpayment behavior is documented contrary to RelayKit’s generated API schema

   • Bug
     • features/deposit-addresses.mdx:66,900-901 and the matching changelog entry at references/api/changelog.mdx:157 state that a strict EXACT_INPUT overpayment fills the whole deposit and does not refund the excess. The current public RelayKit generated API type at packages/sdk/src/types/api.ts:798 says strict overpayments fill the quoted amount and refund excess in a separate refund leg, and does not distinguish EXACT_INPUT. The prior documentation version stated this same generic behavior.
   • Cause
     • The documentation change introduced a trade-type-specific exception that is absent from the authoritative RelayKit API schema generated from the service contract.
   • Fix
     • Restore the generic strict-overpayment wording (quoted fill plus separate excess refund), or obtain and cite an updated authoritative API schema/service implementation that explicitly documents the claimed EXACT_INPUT exception before publishing it.

   _{Ran code and verified through T-Rex}

_{Reviews (1): Last reviewed commit: "Clarify exact-input strict deposit addre..." | Re-trigger Greptile}

[greptile-apps]

Strict overpayment contract mismatch

The new EXACT_INPUT exception says an overpayment fills the entire deposited amount without refunding the excess. RelayKit’s current generated API schema defines strict deposit-address overpayments as filling the quoted amount and returning the excess in a separate refund leg, with no trade-type exception. The same unsupported exception is repeated in the comparison table and the May 7 changelog entry. Restore the generic quoted-fill/excess-refund wording, or update the authoritative API contract before publishing this behavior.

Artifacts

Strict-overpayment live quote validation script

• This authored shell script submits safe quote-only requests for both trade types and prints the current public RelayKit schema, showing the validation procedure without sending funds.

Strict-overpayment behavior before the documentation change

• This command capture reads the base revision’s comparison-table row, showing that it documented all strict overpayments as quoted-fill plus excess-refund.

Live strict quotes and current RelayKit schema

• This executed capture shows successful strict `EXACT_INPUT` and `EXACT_OUTPUT` quotes and then RelayKit’s generated schema stating strict overpayments refund excess, contradicting the new exception.

MDX structural smoke-check output

• This captured failed smoke check is included for completeness; it found that the changelog intentionally has no fenced code block, not a defect in the changed documentation.

_{Ran code and verified through T-Rex}