From 687ec2d163ffea1e561084c2b3812d955e2bae2c Mon Sep 17 00:00:00 2001 From: Ted Palmer Date: Tue, 23 Jun 2026 15:35:57 -0400 Subject: [PATCH 1/8] Requests v3 migration guide --- docs.json | 6 + references/api/api_core_concepts/fees.mdx | 14 +- .../api_guides/migrating-to-requests-v3.mdx | 464 ++++++++++++++++++ style.css | 23 +- 4 files changed, 501 insertions(+), 6 deletions(-) create mode 100644 references/api/api_guides/migrating-to-requests-v3.mdx diff --git a/docs.json b/docs.json index 5867696d..e41a654a 100644 --- a/docs.json +++ b/docs.json @@ -117,6 +117,12 @@ "references/api/api_guides/webhooks" ] }, + { + "group": "Migration Guides", + "pages": [ + "references/api/api_guides/migrating-to-requests-v3" + ] + }, { "group": "Chains, Tokens, Contracts", "pages": [ diff --git a/references/api/api_core_concepts/fees.mdx b/references/api/api_core_concepts/fees.mdx index fe8d0253..fa6f218c 100644 --- a/references/api/api_core_concepts/fees.mdx +++ b/references/api/api_core_concepts/fees.mdx @@ -115,25 +115,29 @@ _Please note that the above fee structure applies to standard cases. In certain ## Fees in the API -Both the quote API and the requests API return a request's fees in the `expandedPriceImpact` object, which breaks them down into the following components: +[`GET /requests/v3`](/references/api/get-requests) returns a request's fees in the `data.fees` object, with `quoted` (estimated at quote time) and `actual` (computed at fill time) values. It breaks fees down into the following components: **execution** - Execution fees covering network gas on the origin and/or destination chain plus the flat fee. **swap** - Swap costs from cross-currency and cross-chain exchange, including DEX fees, swap slippage, and solver rebalancing. -**relay** - The Relay fee, the flat basis-point fee charged by Relay for routing and meta-aggregation services. +**platform** - The platform fee, the flat basis-point fee charged by Relay for routing and meta-aggregation services. **app** - App fees added on top by the integrator, when present. **sponsored** - The portion of fees the integrator subsidizes on behalf of the user via [Fee Sponsorship](/features/fee-sponsorship). -When displaying fees to users, we recommend mapping the `expandedPriceImpact` fields as follows: -- **relay** → Provider Fee +When displaying fees to users, we recommend mapping the `data.fees` fields as follows: +- **platform** → Provider Fee - **app** → Your App's Fee - **swap** + **execution** → Swap Impact + +In the quote API and [`GET /requests/v2`](/references/api/get-requests), this same breakdown is returned as the `expandedPriceImpact` object, and the **platform** component is named **relay**. + + ## Fee Sponsorship Integrators with [Fee Sponsorship](/features/fee-sponsorship) enabled can subsidize fees for their users. By default, setting **`subsidizeFees`** to `true` sponsors all fee components. @@ -147,7 +151,7 @@ See the [Fee Sponsorship Doc](/features/fee-sponsorship) for setup details. The `fees` object is deprecated. It is still returned from the quote API and the [`GET /requests/v2`](/references/api/get-requests) API for backwards compatibility, but it only reports Relay-related fees and does not reflect the full cost of a request. Do not rely on it for new integrations. -To understand or display the complete fee breakdown of a request, use the [`expandedPriceImpact`](#fees-in-the-api) object instead, which covers execution, swap, relay, app, and sponsored fees. +To understand or display the complete fee breakdown of a request, use the [`data.fees`](#fees-in-the-api) object in `GET /requests/v3` (or `expandedPriceImpact` in the quote API and `GET /requests/v2`) instead, which covers execution, swap, platform, app, and sponsored fees. The deprecated `fees` object is segmented into the following fields: diff --git a/references/api/api_guides/migrating-to-requests-v3.mdx b/references/api/api_guides/migrating-to-requests-v3.mdx new file mode 100644 index 00000000..c1cc8767 --- /dev/null +++ b/references/api/api_guides/migrating-to-requests-v3.mdx @@ -0,0 +1,464 @@ +--- +title: "Migrating to Requests v3" +description: "What changed in GET /requests/v3 and how to upgrade from v2." +--- + +`GET /requests/v3` is the latest version of the Requests API. It gives you a richer query surface with advanced filtering across status, chains, amounts, addresses, time, and more, plus a cleaner and more consistent response. This guide covers every change and how to upgrade. v2 stays available, so you can migrate at your own pace. + + + `x-api-key` is now required. Every v3 request authenticates against an active API key. See [API Keys](/references/api/api-keys) for details. + + +## Response shape + +The same request shown in full for v2 and v3, plus a focused diff of what moved. + + + + ```json + { + "id": "0x0000348634...", + "status": "success", + "user": "0xe7a2052a...", + "recipient": "0x07082933...", + "depositAddress": null, + "moonpayId": null, + "referrer": "funxyz|su4gnoxz14", + "data": { + "slippageTolerance": "0", + "failReason": "N/A", + "refundFailReason": "N/A", + "subsidizedRequest": true, + "price": "10000000000", + "currency": "usdc", + "currencyObject": { "chainId": 8453, "address": "0x833589...", "symbol": "USDC", "name": "USD Coin", "decimals": 6, "metadata": { "logoURI": "https://...", "verified": true } }, + "feeCurrency": "usdc.e", + "feeCurrencyObject": { "chainId": 137, "address": "0x2791bc...", "symbol": "USDC.e", "name": "USDCoin (bridged)", "decimals": 6, "metadata": { "logoURI": "https://...", "verified": true } }, + "appFeeCurrencyObject": { "chainId": 137, "address": "0x2791bc...", "symbol": "USDC.e", "name": "USDCoin (bridged)", "decimals": 6 }, + "fees": { "gas": "1160", "fixed": "0", "price": "1999930" }, + "feesUsd": { "gas": "0.001159", "fixed": "0.000000", "price": "1.999162" }, + "appFees": [ { "recipient": "0xdfd877...", "bps": "5", "amount": "5000000", "amountUsd": "4.997980", "amountUsdCurrent": "4.998080" } ], + "paidAppFees": [ { "recipient": "0xdfd877...", "bps": "5", "amount": "5000000", "amountUsd": "4.997980", "amountUsdCurrent": "4.998080" } ], + "subsidizedFee": { + "origin": { "amount": "7001090", "address": "0x2791bc...", "chainId": 137 }, + "sponsor": { "amount": "7000949", "address": "0x833589...", "chainId": 8453 }, + "amountUsd": "6.998261", + "amountUsdCurrent": "6.998401" + }, + "expandedPriceImpact": { + "quoted": { "swap": { "usd": "-1.999380" }, "execution": { "usd": "-0.001160" }, "relay": { "usd": "0.000000" }, "app": { "usd": "-4.998625" }, "sponsored": { "usd": "6.999165" } }, + "actual": { "swap": { "usd": "-1.999380" }, "execution": { "usd": "-0.001160" }, "relay": { "usd": "0.000000" }, "app": { "usd": "-4.998625" }, "sponsored": { "usd": "6.999165" } } + }, + "feeSponsorship": { + "quoted": { + "selectedComponents": ["execution", "swap", "relay", "app"], + "capHit": false, + "components": { + "execution": { "selected": true, "total": { "currency": { "chainId": 137, "symbol": "USDC.e", "decimals": 6 }, "amount": "1160", "amountFormatted": "0.00116", "amountUsd": "0.001160", "minimumAmount": "1160" }, "sponsored": { "currency": { "chainId": 137, "symbol": "USDC.e", "decimals": 6 }, "amount": "1160", "amountUsd": "0.001160" }, "userPays": { "currency": { "chainId": 137, "symbol": "USDC.e", "decimals": 6 }, "amount": "0", "amountUsd": "0" } }, + "swap": { "selected": true, "total": { "currency": { "chainId": 137, "symbol": "USDC.e", "decimals": 6 }, "amount": "1999380", "amountUsd": "1.999380" }, "sponsored": { "amount": "1999380", "amountUsd": "1.999380" }, "userPays": { "amount": "0", "amountUsd": "0" } }, + "relay": { "selected": true, "total": { "amount": "0", "amountUsd": "0.000000" }, "sponsored": { "amount": "0", "amountUsd": "0" }, "userPays": { "amount": "0", "amountUsd": "0" } }, + "app": { "selected": true, "total": { "amount": "5000000", "amountUsd": "4.998625" }, "sponsored": { "amount": "5000000", "amountUsd": "4.998625" }, "userPays": { "amount": "0", "amountUsd": "0" } } + }, + "sponsoredTotal": { "currency": { "chainId": 137, "symbol": "USDC.e", "decimals": 6 }, "amount": "7001090", "amountFormatted": "7.00109", "amountUsd": "6.999165" }, + "userPaysTotal": { "currency": { "chainId": 137, "symbol": "USDC.e", "decimals": 6 }, "amount": "0", "amountUsd": "0" } + }, + "actual": { "selectedComponents": ["execution", "swap", "relay", "app"], "capHit": false, "components": { "execution": "…", "swap": "…", "relay": "…", "app": "…" }, "sponsoredTotal": { "amount": "7001090", "amountUsd": "6.999165" }, "userPaysTotal": { "amount": "0", "amountUsd": "0" } } + }, + "inTxs": [ { "hash": "0xcd4d70...", "fee": "139725000000000", "block": 87433122, "type": "onchain", "chainId": 137, "timestamp": 1779747672, "status": "success", "data": {}, "stateChanges": [] } ], + "outTxs": [ { "hash": "0x1c0089...", "fee": "433800000000", "block": 46479163, "type": "onchain", "chainId": 8453, "timestamp": 1779747673, "status": "success", "data": {}, "stateChanges": [] } ], + "usesExternalLiquidity": false, + "timeEstimate": 4, + "metadata": { + "sender": "0xE7a205...", + "recipient": "0x070829...", + "currencyIn": { "currency": { "chainId": 137, "address": "0x2791bc...", "symbol": "USDC.e", "name": "USDCoin (bridged)", "decimals": 6, "metadata": { "logoURI": "https://...", "verified": true } }, "amount": "10000000000", "amountFormatted": "10000.0", "amountUsd": "9997.600000", "amountUsdCurrent": "9996.000000", "minimumAmount": "10000000000" }, + "currencyOut": { "currency": { "chainId": 8453, "address": "0x833589...", "symbol": "USDC", "name": "USD Coin", "decimals": 6, "metadata": { "logoURI": "https://...", "verified": true } }, "amount": "10000000000", "amountFormatted": "10000.0", "amountUsd": "9997.600000", "amountUsdCurrent": "9996.000000", "minimumAmount": "10000000000" }, + "rate": "1", + "route": { + "origin": { "inputCurrency": { "currency": { "chainId": 137, "symbol": "USDC.e", "decimals": 6 }, "amount": "10000000000" }, "outputCurrency": { "currency": { "chainId": 137, "symbol": "USDC.e", "decimals": 6 }, "amount": "10000000000" }, "router": "relay" }, + "destination": { "inputCurrency": { "currency": { "chainId": 8453, "symbol": "USDC", "decimals": 6 }, "amount": "10000000000" }, "outputCurrency": { "currency": { "chainId": 8453, "symbol": "USDC", "decimals": 6 }, "amount": "10000000000" }, "router": "relay" } + } + } + }, + "protocol": { + "orderId": "0x...", + "hubType": "onchain", + "isWithdrawable": false, + "solver": { "address": "0x...", "protocolChainId": "8453", "chainId": 8453 }, + "deposit": { "origin": { "amount": "10000000000", "chainId": 137, "currency": "0x2791bc...", "depositor": "0xe7a205...", "depository": "0x...", "onchainId": "0x...", "transactionId": "0xcd4d70..." } }, + "settlement": { "destination": { "fills": [ { "chainId": 8453, "transactionId": "0x1c0089..." } ], "refunds": [] } } + }, + "createdAt": "2026-05-25T22:21:11.161Z", + "updatedAt": "2026-05-25T22:21:51.291Z" + } + ``` + + + ```json + { + "id": "0x0000348634...", + "status": "success", + "user": "0xe7a2052a...", + "recipient": "0x07082933...", + "refundTo": null, + "depositAddress": null, + "title": "Crosschain Swap", + "data": { + "slippageTolerance": "0", + "failReason": null, + "refundFailReason": null, + "failedTxHash": null, + "failedTxBlockNumber": null, + "failedCallData": null, + "quotedOutputAmount": "10000000000", + "usesExternalLiquidity": false, + "timeEstimate": 4, + "triggeredByFastFill": null, + "inTxs": [ { "txHash": "0xcd4d70...", "fee": "139725000000000", "block": 87433122, "type": "onchain", "chainId": 137, "timestamp": 1779747672, "status": "success", "data": {}, "stateChanges": [] } ], + "outTxs": [ { "txHash": "0x1c0089...", "fee": "433800000000", "block": 46479163, "type": "onchain", "chainId": 8453, "timestamp": 1779747673, "status": "success", "data": {}, "stateChanges": [] } ], + "appFees": { + "quoted": [ { "recipient": "0xdfd877...", "bps": "5", "amount": "5000000", "amountFormatted": "5.0" } ], + "actual": [ { "recipient": "0xdfd877...", "bps": "5", "amount": "5000000", "amountFormatted": "5.0", "amountUsd": "4.997980" } ], + "currency": { "chainId": 137, "address": "0x2791bc...", "symbol": "USDC.e", "name": "USDCoin (bridged)", "decimals": 6, "metadata": { "logoURI": "https://...", "verified": true } } + }, + "fees": { + "quoted": { "swap": { "usd": "-1.999380", "amount": "1999380", "amountFormatted": "1.99938" }, "execution": { "usd": "-0.001160", "amount": "1160", "amountFormatted": "0.00116" }, "platform": { "usd": "0.000000", "amount": "0", "amountFormatted": "0" }, "app": { "usd": "-4.998625", "amount": "5000000", "amountFormatted": "5.0" }, "sponsored": { "usd": "6.999165", "amount": "7001090", "amountFormatted": "7.00109" } }, + "actual": { "swap": { "usd": "-1.999380" }, "execution": { "usd": "-0.001160" }, "platform": { "usd": "0.000000" }, "app": { "usd": "-4.998625" }, "sponsored": { "usd": "6.999165" } }, + "currency": { "chainId": 137, "address": "0x2791bc...", "symbol": "USDC.e", "name": "USDCoin (bridged)", "decimals": 6, "metadata": { "logoURI": "https://...", "verified": true } } + }, + "feeSponsorship": { + "quoted": { + "selectedComponents": ["execution", "swap", "platform", "app"], + "maxSubsidizationAmount": null, + "capHit": false, + "components": { + "execution": { "selected": true, "total": { "amount": "1160", "amountFormatted": "0.00116", "amountUsd": "0.001160", "minimumAmount": "1160" }, "sponsored": { "amount": "1160", "amountUsd": "0.001160" }, "userPays": { "amount": "0", "amountUsd": "0" } }, + "swap": { "selected": true, "total": { "amount": "1999380", "amountUsd": "1.999380" }, "sponsored": { "amount": "1999380", "amountUsd": "1.999380" }, "userPays": { "amount": "0", "amountUsd": "0" } }, + "platform": { "selected": true, "total": { "amount": "0", "amountUsd": "0" }, "sponsored": { "amount": "0", "amountUsd": "0" }, "userPays": { "amount": "0", "amountUsd": "0" } }, + "app": { "selected": true, "total": { "amount": "5000000", "amountUsd": "4.998625" }, "sponsored": { "amount": "5000000", "amountUsd": "4.998625" }, "userPays": { "amount": "0", "amountUsd": "0" } } + }, + "sponsoredTotal": { "amount": "7001090", "amountFormatted": "7.00109", "amountUsd": "6.999165" }, + "userPaysTotal": { "amount": "0", "amountFormatted": "0", "amountUsd": "0" } + }, + "actual": { "selectedComponents": ["execution", "swap", "platform", "app"], "capHit": false, "components": { "execution": "…", "swap": "…", "platform": "…", "app": "…" }, "sponsoredTotal": { "amount": "7001090", "amountUsd": "6.999165" }, "userPaysTotal": { "amount": "0", "amountUsd": "0" }, "sponsorPayment": { "amount": "7000949", "address": "0x833589...", "chainId": 8453 } }, + "currency": { "chainId": 137, "address": "0x2791bc...", "symbol": "USDC.e", "decimals": 6 } + }, + "swap": { + "sender": "0xE7a205...", + "recipient": "0x070829...", + "currencyIn": { "currency": { "chainId": 137, "address": "0x2791bc...", "symbol": "USDC.e", "name": "USDCoin (bridged)", "decimals": 6, "metadata": { "logoURI": "https://...", "verified": true } }, "amount": "10000000000", "amountFormatted": "10000.0", "amountUsd": "9997.600000", "amountUsdCurrent": "9996.000000", "minimumAmount": "10000000000" }, + "currencyOut": { "currency": { "chainId": 8453, "address": "0x833589...", "symbol": "USDC", "name": "USD Coin", "decimals": 6, "metadata": { "logoURI": "https://...", "verified": true } }, "amount": "10000000000", "amountFormatted": "10000.0", "amountUsd": "9997.600000", "amountUsdCurrent": "9996.000000", "minimumAmount": "10000000000" }, + "rate": "1" + }, + "platformFee": null, + "route": { + "origin": { "inputCurrency": { "currency": { "chainId": 137, "symbol": "USDC.e", "decimals": 6 }, "amount": "10000000000" }, "outputCurrency": { "currency": { "chainId": 137, "symbol": "USDC.e", "decimals": 6 }, "amount": "10000000000" }, "router": "relay", "includedSwapSources": [] }, + "destination": { "inputCurrency": { "currency": { "chainId": 8453, "symbol": "USDC", "decimals": 6 }, "amount": "10000000000" }, "outputCurrency": { "currency": { "chainId": 8453, "symbol": "USDC", "decimals": 6 }, "amount": "10000000000" }, "router": "relay", "includedSwapSources": [] } + }, + "refundCurrencyData": null, + "externalMetadata": { "moonpayId": null } + }, + "protocol": { + "orderId": "0x...", + "hubType": "onchain", + "isWithdrawable": false, + "solver": { "address": "0x...", "protocolChainId": "8453", "chainId": 8453 }, + "deposit": { "origin": { "amount": "10000000000", "chainId": 137, "currency": "0x2791bc...", "depositor": "0xe7a205...", "depository": "0x...", "onchainId": "0x...", "transactionId": "0xcd4d70..." } }, + "settlement": { "destination": { "fills": [ { "chainId": 8453, "transactionId": "0x1c0089..." } ], "refunds": [] } } + }, + "createdAt": "2026-05-25T22:21:11.161Z", + "updatedAt": "2026-05-25T22:21:51.291Z" + } + ``` + + + ```diff + { + "id": "0x0000348634...", + "status": "success", + - "moonpayId": null, + - "referrer": "funxyz|su4gnoxz14", + + "refundTo": null, + + "title": "Crosschain Swap", + + "depositAddress": null, + "data": { + - "failReason": "N/A", + - "refundFailReason": "N/A", + + "failReason": null, + + "refundFailReason": null, + - "subsidizedRequest": true, + - "price": "10000000000", + + "quotedOutputAmount": "10000000000", + - "fees": { "gas": "1160", "fixed": "0", "price": "1999930" }, + - "feesUsd": { "gas": "0.001159", "...": "..." }, + - "currency": "usdc", + - "currencyObject": { "...": "..." }, + - "feeCurrency": "usdc.e", + - "feeCurrencyObject": { "...": "..." }, + - "appFees": [ { "bps": "5", "amount": "5000000", "amountUsd": "4.99" } ], + - "paidAppFees": [ { "bps": "5", "amount": "5000000", "amountUsd": "4.99" } ], + + "appFees": { + + "quoted": [ { "bps": "5", "amount": "5000000" } ], + + "actual": [ { "bps": "5", "amount": "5000000", "amountUsd": "4.99" } ], + + "currency": { "symbol": "USDC.e", "decimals": 6 } + + }, + - "subsidizedFee": { "amountUsd": "6.99", "...": "..." }, + - "expandedPriceImpact": { "quoted": { "relay": { "usd": "0" }, "...": "..." } }, + + "fees": { + + "quoted": { "swap": {}, "execution": {}, "platform": {}, "app": {}, "sponsored": {} }, + + "actual": { "...": "..." }, + + "currency": { "symbol": "USDC.e", "decimals": 6 } + + }, + "feeSponsorship": { + - "quoted": { "selectedComponents": ["execution","swap","relay","app"], "components": { "relay": {} } } + + "quoted": { "selectedComponents": ["execution","swap","platform","app"], "components": { "platform": {} } }, + + "actual": { "sponsorPayment": { "amount": "...", "chainId": 8453 } }, + + "currency": { "symbol": "USDC.e", "decimals": 6 } + }, + - "inTxs": [ { "hash": "0xcd4d70..." } ], + - "outTxs": [ { "hash": "0x1c0089..." } ], + + "inTxs": [ { "txHash": "0xcd4d70..." } ], + + "outTxs": [ { "txHash": "0x1c0089..." } ], + - "metadata": { "currencyIn": {}, "currencyOut": {}, "rate": "1", "route": {} } + + "swap": { "currencyIn": {}, "currencyOut": {}, "rate": "1" }, + + "route": { "origin": {}, "destination": {} }, + + "externalMetadata": { "moonpayId": null } + } + } + ``` + + + + + **`data.fees` has changed meaning.** The key `fees` is reused for a different shape. In v2, `data.fees` was raw wei (`gas`/`fixed`/`price`/`gateway`). In v3 that object is removed, and `data.fees` now holds the per‑component USD breakdown that v2 called `expandedPriceImpact`. Code reading `data.fees.gas` will break — read `data.fees.quoted` / `data.fees.actual` instead. + + +## What changed + +Every individual change, grouped by request side and response side. + +### Request & querying + + + + ```diff + GET /requests/v3 + Headers: + + x-api-key: # now required + ``` + + The `x-api-key` request header is now required. Every request authenticates against an active API key. See [API Keys](/references/api/api-keys) for details. + + + + v3 exposes a broad filter surface. All parameters are optional and combine with AND semantics unless noted. + + | Category | Parameters | + | --- | --- | + | **Search** | `term` (request id, wallet, deposit address, every tx hash), `id`, `orderId`, `depositTxHash`, `fillTxHash`, `refundTxHash` | + | **Chain** | `originChainId`, `destinationChainId`, `chainId` (either direction), `privateChainsToInclude` | + | **Address** | `user`, `depositAddress`, `recipient` | + | **Status / routing** | `status`, `failReason`, `refundFailReason`, `apiKey`, `title` | + | **Currency** | `currencyInChainId`, `currencyOutChainId`, `currencyInAddress`, `currencyOutAddress` | + | **Ranges** | `startTimestamp`, `endTimestamp`, `startBlock`, `endBlock`, `amountUsdMin`/`Max`, `appFeesAmountUsdMin`/`Max`, `fillTimeMin`/`Max` | + | **Other** | `features`, `includeChildRequests`, `filters` (AND/OR), `sortBy`, `sortDirection` | + + + `term` is a single unified search across request id, wallet, deposit address, and every transaction hash (deposit, fill, refund, failed, chain‑entry). It replaces the v2 pattern of running separate `user` / `hash` / `id` lookups and merging the results. + + + **Sorting.** `sortBy` accepts `createdAt` (default), `updatedAt`, or `amountUsd`. `sortDirection` is `asc` or `desc` (defaults to `desc` for time fields, `asc` for `amountUsd`). + + **Advanced filtering (AND / OR composition).** The `filters` parameter takes a JSON‑encoded array of groups. Fields **within** a group are AND'd; the groups themselves are OR'd. Top‑level parameters still apply. + + ```bash + # "(depositAddress=0xabc AND originChainId=8453) OR (depositAddress=0x123 AND originChainId=1)" + GET /requests/v3?filters=[{"depositAddress":"0xabc","originChainId":8453},{"depositAddress":"0x123","originChainId":1}] + ``` + + OR groups support identity, address, chain, currency, and status‑style fields. Range filters and `features` are top‑level only. + + **Removed & changed parameters.** + - `hash` is removed; use `term`, or the targeted `depositTxHash` / `fillTxHash` / `refundTxHash`. + - `includeAuthenticatedData` is removed; integrator‑only fields are returned automatically for requests created with your API key. + - `referrer` is removed from both the request and the response. + + + + +### Response fields + + + + The response envelope now includes a `total`, and `continuation` is an opaque cursor you pass back to fetch the next page. `limit` defaults to 20 and is capped at **50**. + + ```diff + - // v2: offset-style paging, no total + + "total": 12345, + + "continuation": "eyJ..." // opaque cursor, pass back as ?continuation= + ``` + + + + The `currency` (string) + `currencyObject` (object) duality is removed everywhere, along with `feeCurrency`/`feeCurrencyObject` and `appFeeCurrencyObject`. Every currency is a single object: `{ chainId, address, symbol, name, decimals, metadata }`. Amount objects carry that currency plus `amount`, `amountFormatted`, `amountUsd`, and where relevant `amountUsdCurrent`, `minimumAmount`. + + ```diff + - "currency": "usdc", + - "currencyObject": { "chainId": 137, "symbol": "USDC", "decimals": 6 } + + // read the currency object directly off the amount, e.g. data.swap.currencyIn.currency + ``` + + + + `data.expandedPriceImpact` is renamed to **`data.fees`** (and the old wei `data.fees` / `data.feesUsd` are removed). Each phase (`quoted`, `actual`) breaks fees into `swap`, `execution`, `platform`, `app`, and `sponsored`, with the shared currency hoisted to `data.fees.currency`. The `relay` component is renamed to **`platform`**, and per‑component values now include `amount` and `amountFormatted` in addition to `usd`. + + ```diff + - "expandedPriceImpact": { "quoted": { "swap": { "usd": "-1.99" }, "relay": { "usd": "0" } } } + + "fees": { + + "quoted": { "swap": { "usd": "-1.99", "amount": "...", "amountFormatted": "..." }, "platform": { "usd": "0" } }, + + "actual": { "...": "..." }, + + "currency": { "symbol": "USDC.e" } + + } + ``` + + + + `data.subsidizedRequest` and `data.subsidizedFee` are removed. `data.feeSponsorship` is now the only sponsorship source — determine whether a request was sponsored from `feeSponsorship.{quoted,actual}.sponsoredTotal.amountUsd`. The `relay` bucket is renamed to **`platform`**, the shared `currency` is hoisted to `feeSponsorship.currency`, and the `actual` phase gains a `sponsorPayment` object. + + ```diff + - "subsidizedRequest": true, + - "subsidizedFee": { "amountUsd": "6.99" }, + "feeSponsorship": { + - "quoted": { "selectedComponents": ["execution","swap","relay","app"], "components": { "relay": {} } } + + "quoted": { "selectedComponents": ["execution","swap","platform","app"], "components": { "platform": {} } }, + + "actual": { "sponsorPayment": { "amount": "...", "chainId": 8453 } }, + + "currency": { "symbol": "USDC.e" } + } + ``` + + + + The parallel `appFees` (quoted) and `paidAppFees` (actual) arrays are consolidated into one object with explicit `quoted` / `actual` keys and a hoisted `currency`. + + ```diff + - "appFees": [ { "bps": "5", "amount": "5000000" } ], + - "paidAppFees": [ { "bps": "5", "amount": "5000000", "amountUsd": "4.99" } ], + + "appFees": { + + "quoted": [ { "bps": "5", "amount": "5000000" } ], + + "actual": [ { "bps": "5", "amount": "5000000", "amountUsd": "4.99" } ], + + "currency": { "symbol": "USDC.e" } + + } + ``` + + + + The `data.metadata` catch‑all is removed. Its swap fields move to **`data.swap`** (`sender`, `recipient`, `currencyIn`, `currencyOut`, `rate`, `currencyGasTopup`) and the routing info moves to **`data.route`** (`origin` / `destination` with `inputCurrency`, `outputCurrency`, `router`, `includedSwapSources`). + + ```diff + - "metadata": { "currencyIn": {}, "currencyOut": {}, "rate": "1", "route": {} } + + "swap": { "currencyIn": {}, "currencyOut": {}, "rate": "1" }, + + "route": { "origin": {}, "destination": {} } + ``` + + + + Inside `inTxs[]` and `outTxs[]`, the `hash` field is renamed to `txHash`. The array names themselves are unchanged. + + ```diff + - "inTxs": [ { "hash": "0xcd4d70..." } ], + - "outTxs": [ { "hash": "0x1c0089..." } ] + + "inTxs": [ { "txHash": "0xcd4d70..." } ], + + "outTxs": [ { "txHash": "0x1c0089..." } ] + ``` + + + + The response `status` enum is now `pending`, `waiting`, `depositing`, `submitted`, `success`, `failure`, `refund`. `depositing` and `submitted` are new; the v2 `delayed` value is gone. The `status` **filter** accepts `success`, `failure`, `refund`, `pending`, `depositing`. + + ```diff + - status ∈ { pending, waiting, delayed, success, failure, refund } + + status ∈ { pending, waiting, depositing, submitted, success, failure, refund } + ``` + + + + - `moonpayId` moves from the root to **`data.externalMetadata.moonpayId`**. + - `referrer` is **removed** from the response. + - **`refundTo`** (refund target for deposit‑address transactions) is **added** at the root. + - **`title`** (the request type: `Bridge`, `Crosschain Swap`, `Same-chain Swap`, `Send`, `Wrap`, `Unwrap`, `Call`) is **added** at the root. + - **`depositAddress`** is now a structured object: `{ address, type: "strict" | "open", depositor, depositTxHash }`. + - `data.price` → **`data.quotedOutputAmount`** (the amount the solver committed to send at solve time — distinct from the actual received amount in `data.swap.currencyOut.amount`). + - `failReason` / `refundFailReason` use **`null`** instead of the string `"N/A"`. + + + +## Field migration reference + + + + | v2 | v3 | + | --- | --- | + | `data.expandedPriceImpact` | `data.fees` (component `relay` → `platform`) | + | `data.price` | `data.quotedOutputAmount` | + | `data.metadata.{currencyIn,currencyOut,sender,recipient,rate,currencyGasTopup}` | `data.swap.*` | + | `data.metadata.route` | `data.route` | + | `data.appFees` (quoted) + `data.paidAppFees` (actual) | `data.appFees.{quoted,actual,currency}` | + | `inTxs[].hash` / `outTxs[].hash` | `inTxs[].txHash` / `outTxs[].txHash` | + | `feeSponsorship…components.relay` | `feeSponsorship…components.platform` | + | `moonpayId` (root) | `data.externalMetadata.moonpayId` | + | `depositAddress` (nullable) | `depositAddress` object `{address,type,depositor,depositTxHash}` | + + + | Removed in v3 | Replacement | + | --- | --- | + | `data.fees` (wei `gas`/`fixed`/`price`/`gateway`) | `data.fees` (now USD price‑impact) | + | `data.feesUsd` | `data.fees` | + | `data.currency` / `data.currencyObject` | currency object on each amount | + | `data.feeCurrency` / `data.feeCurrencyObject` | currency hoisted into fee objects | + | `data.appFeeCurrencyObject` | `data.appFees.currency` | + | `data.subsidizedRequest` / `data.subsidizedFee` | `data.feeSponsorship` | + | `data.metadata` (catch‑all) | `data.swap` + `data.route` | + | `referrer` (request & response) | — | + | `?includeAuthenticatedData` | automatic for requests created with your API key | + | `?hash` | `term` / `depositTxHash` / `fillTxHash` / `refundTxHash` | + | status `delayed` | `depositing` / `submitted` | + + + | Added in v3 | Notes | + | --- | --- | + | `total` (envelope) | total matching the current filters | + | `continuation` cursor | opaque pagination cursor | + | `title` | request type | + | `refundTo` | refund target for deposit‑address flows | + | `data.externalMetadata` | partner correlation IDs (e.g. `moonpayId`) | + | `feeSponsorship.actual.sponsorPayment` | what the sponsor actually paid | + | broad filter/sort surface | see [Filtering, search & sorting](#what-changed) | + + + +## Migration checklist + + + + Point requests at `GET /requests/v3` and send `x-api-key` (now required). Drop `includeAuthenticatedData` and any `referrer` parameter. + + + Stop reading `data.fees.gas` / `feesUsd`. Read the per‑component USD breakdown from `data.fees.quoted` / `data.fees.actual`, and rename the `relay` component to `platform`. + + + Replace `data.metadata.currencyIn/out/...` with `data.swap.*` and `data.metadata.route` with `data.route`. Drop `currency`/`currencyObject` string handling — read the single currency object. + + + Read `data.appFees.quoted` / `data.appFees.actual`. Replace `subsidizedRequest`/`subsidizedFee` with `data.feeSponsorship`, and rename its `relay` bucket to `platform`. + + + Rename `inTxs[].hash` / `outTxs[].hash` to `txHash`. Handle the new `depositing` / `submitted` statuses (and remove `delayed`). Treat `failReason` / `refundFailReason` as `null` rather than `"N/A"`. + + + Replace separate `user`/`hash`/`id` lookups with a single `term` search where it fits. Use `total` for counts and pass `continuation` back for the next page (`limit` max 50). + + + + + Integrator‑only data — revenue share via `platformFee`, un‑redacted pending output, and `refundCurrencyData` — is returned automatically for requests created with your API key. There's no opt‑in flag to set. + diff --git a/style.css b/style.css index a0d383dc..3f4ad125 100644 --- a/style.css +++ b/style.css @@ -394,4 +394,25 @@ margin: 0; padding: 0; } - } \ No newline at end of file + } +/* ── Stronger red/green diff highlighting in code blocks ─────────────────── + Mintlify renders code via Shiki; the default diff line tint is faint. + Boost the contrast for ```diff blocks (and [!code ++]/[!code --] lines). + Tune the rgba alpha values below if you want it stronger/softer. */ +.line.diff.add, +span.line.diff.add, +.line.diff.remove, +span.line.diff.remove { + display: inline-block; + width: 100%; + margin: 0 -1rem; + padding: 0 1rem; +} +.line.diff.add, +span.line.diff.add { + background-color: rgba(46, 160, 67, 0.24) !important; +} +.line.diff.remove, +span.line.diff.remove { + background-color: rgba(248, 81, 73, 0.22) !important; +} From ee1fb0e5329ffa59f8076e55d235ed3ddb1bb949 Mon Sep 17 00:00:00 2001 From: Ted Palmer Date: Tue, 23 Jun 2026 17:05:51 -0400 Subject: [PATCH 2/8] feedback --- .../api_guides/migrating-to-requests-v3.mdx | 129 +++++++++--------- style.css | 21 --- 2 files changed, 66 insertions(+), 84 deletions(-) diff --git a/references/api/api_guides/migrating-to-requests-v3.mdx b/references/api/api_guides/migrating-to-requests-v3.mdx index c1cc8767..011b4a1f 100644 --- a/references/api/api_guides/migrating-to-requests-v3.mdx +++ b/references/api/api_guides/migrating-to-requests-v3.mdx @@ -15,7 +15,7 @@ The same request shown in full for v2 and v3, plus a focused diff of what moved. - ```json + ```json expandable { "id": "0x0000348634...", "status": "success", @@ -23,7 +23,7 @@ The same request shown in full for v2 and v3, plus a focused diff of what moved. "recipient": "0x07082933...", "depositAddress": null, "moonpayId": null, - "referrer": "funxyz|su4gnoxz14", + "referrer": "my-app|user-123", "data": { "slippageTolerance": "0", "failReason": "N/A", @@ -94,12 +94,13 @@ The same request shown in full for v2 and v3, plus a focused diff of what moved. ``` - ```json + ```json expandable { "id": "0x0000348634...", "status": "success", "user": "0xe7a2052a...", "recipient": "0x07082933...", + "referrer": "my-app|user-123", "refundTo": null, "depositAddress": null, "title": "Crosschain Swap", @@ -172,59 +173,59 @@ The same request shown in full for v2 and v3, plus a focused diff of what moved. ``` - ```diff - { - "id": "0x0000348634...", - "status": "success", - - "moonpayId": null, - - "referrer": "funxyz|su4gnoxz14", - + "refundTo": null, - + "title": "Crosschain Swap", - + "depositAddress": null, - "data": { - - "failReason": "N/A", - - "refundFailReason": "N/A", - + "failReason": null, - + "refundFailReason": null, - - "subsidizedRequest": true, - - "price": "10000000000", - + "quotedOutputAmount": "10000000000", - - "fees": { "gas": "1160", "fixed": "0", "price": "1999930" }, - - "feesUsd": { "gas": "0.001159", "...": "..." }, - - "currency": "usdc", - - "currencyObject": { "...": "..." }, - - "feeCurrency": "usdc.e", - - "feeCurrencyObject": { "...": "..." }, - - "appFees": [ { "bps": "5", "amount": "5000000", "amountUsd": "4.99" } ], - - "paidAppFees": [ { "bps": "5", "amount": "5000000", "amountUsd": "4.99" } ], - + "appFees": { - + "quoted": [ { "bps": "5", "amount": "5000000" } ], - + "actual": [ { "bps": "5", "amount": "5000000", "amountUsd": "4.99" } ], - + "currency": { "symbol": "USDC.e", "decimals": 6 } - + }, - - "subsidizedFee": { "amountUsd": "6.99", "...": "..." }, - - "expandedPriceImpact": { "quoted": { "relay": { "usd": "0" }, "...": "..." } }, - + "fees": { - + "quoted": { "swap": {}, "execution": {}, "platform": {}, "app": {}, "sponsored": {} }, - + "actual": { "...": "..." }, - + "currency": { "symbol": "USDC.e", "decimals": 6 } - + }, - "feeSponsorship": { - - "quoted": { "selectedComponents": ["execution","swap","relay","app"], "components": { "relay": {} } } - + "quoted": { "selectedComponents": ["execution","swap","platform","app"], "components": { "platform": {} } }, - + "actual": { "sponsorPayment": { "amount": "...", "chainId": 8453 } }, - + "currency": { "symbol": "USDC.e", "decimals": 6 } - }, - - "inTxs": [ { "hash": "0xcd4d70..." } ], - - "outTxs": [ { "hash": "0x1c0089..." } ], - + "inTxs": [ { "txHash": "0xcd4d70..." } ], - + "outTxs": [ { "txHash": "0x1c0089..." } ], - - "metadata": { "currencyIn": {}, "currencyOut": {}, "rate": "1", "route": {} } - + "swap": { "currencyIn": {}, "currencyOut": {}, "rate": "1" }, - + "route": { "origin": {}, "destination": {} }, - + "externalMetadata": { "moonpayId": null } - } + ```jsonc expandable + { + "id": "0x0000348634...", + "status": "success", + "moonpayId": null, // [!code --] + "refundTo": null, // [!code ++] + "title": "Crosschain Swap", // [!code ++] + "depositAddress": null, // [!code ++] + "referrer": "my-app|user-123", + "data": { + "failReason": "N/A", // [!code --] + "refundFailReason": "N/A", // [!code --] + "failReason": null, // [!code ++] + "refundFailReason": null, // [!code ++] + "subsidizedRequest": true, // [!code --] + "price": "10000000000", // [!code --] + "quotedOutputAmount": "10000000000", // [!code ++] + "fees": { "gas": "1160", "fixed": "0", "price": "1999930" }, // [!code --] + "feesUsd": { "gas": "0.001159" }, // [!code --] + "currency": "usdc", // [!code --] + "currencyObject": { }, // [!code --] + "feeCurrency": "usdc.e", // [!code --] + "feeCurrencyObject": { }, // [!code --] + "appFees": [ { "bps": "5", "amount": "5000000", "amountUsd": "4.99" } ], // [!code --] + "paidAppFees": [ { "bps": "5", "amount": "5000000", "amountUsd": "4.99" } ], // [!code --] + "appFees": { // [!code ++] + "quoted": [ { "bps": "5", "amount": "5000000" } ], // [!code ++] + "actual": [ { "bps": "5", "amount": "5000000", "amountUsd": "4.99" } ], // [!code ++] + "currency": { "symbol": "USDC.e", "decimals": 6 } // [!code ++] + }, // [!code ++] + "subsidizedFee": { "amountUsd": "6.99" }, // [!code --] + "expandedPriceImpact": { "quoted": { "relay": { "usd": "0" } } }, // [!code --] + "fees": { // [!code ++] + "quoted": { "swap": {}, "execution": {}, "platform": {}, "app": {}, "sponsored": {} }, // [!code ++] + "actual": { }, // [!code ++] + "currency": { "symbol": "USDC.e", "decimals": 6 } // [!code ++] + }, // [!code ++] + "feeSponsorship": { + "quoted": { "selectedComponents": ["execution","swap","relay","app"], "components": { "relay": {} } } // [!code --] + "quoted": { "selectedComponents": ["execution","swap","platform","app"], "components": { "platform": {} } }, // [!code ++] + "actual": { "sponsorPayment": { "amount": "...", "chainId": 8453 } }, // [!code ++] + "currency": { "symbol": "USDC.e", "decimals": 6 } // [!code ++] + }, + "inTxs": [ { "hash": "0xcd4d70..." } ], // [!code --] + "outTxs": [ { "hash": "0x1c0089..." } ], // [!code --] + "inTxs": [ { "txHash": "0xcd4d70..." } ], // [!code ++] + "outTxs": [ { "txHash": "0x1c0089..." } ], // [!code ++] + "metadata": { "currencyIn": {}, "currencyOut": {}, "rate": "1", "route": {} } // [!code --] + "swap": { "currencyIn": {}, "currencyOut": {}, "rate": "1" }, // [!code ++] + "route": { "origin": {}, "destination": {} }, // [!code ++] + "externalMetadata": { "moonpayId": null } // [!code ++] } + } ``` @@ -261,7 +262,7 @@ Every individual change, grouped by request side and response side. | **Status / routing** | `status`, `failReason`, `refundFailReason`, `apiKey`, `title` | | **Currency** | `currencyInChainId`, `currencyOutChainId`, `currencyInAddress`, `currencyOutAddress` | | **Ranges** | `startTimestamp`, `endTimestamp`, `startBlock`, `endBlock`, `amountUsdMin`/`Max`, `appFeesAmountUsdMin`/`Max`, `fillTimeMin`/`Max` | - | **Other** | `features`, `includeChildRequests`, `filters` (AND/OR), `sortBy`, `sortDirection` | + | **Other** | `features`, `includeChildRequests`, `filters` (AND/OR), `sortBy`, `sortDirection`, `includeAuthenticatedData` | `term` is a single unified search across request id, wallet, deposit address, and every transaction hash (deposit, fill, refund, failed, chain‑entry). It replaces the v2 pattern of running separate `user` / `hash` / `id` lookups and merging the results. @@ -280,8 +281,7 @@ Every individual change, grouped by request side and response side. **Removed & changed parameters.** - `hash` is removed; use `term`, or the targeted `depositTxHash` / `fillTxHash` / `refundTxHash`. - - `includeAuthenticatedData` is removed; integrator‑only fields are returned automatically for requests created with your API key. - - `referrer` is removed from both the request and the response. + - `referrer` is no longer a query parameter; it's still returned in the response, but only when `includeAuthenticatedData=true`. @@ -383,7 +383,7 @@ Every individual change, grouped by request side and response side. - `moonpayId` moves from the root to **`data.externalMetadata.moonpayId`**. - - `referrer` is **removed** from the response. + - `referrer` is no longer a query parameter, but it's still returned in the response — **only when `includeAuthenticatedData=true`**. - **`refundTo`** (refund target for deposit‑address transactions) is **added** at the root. - **`title`** (the request type: `Bridge`, `Crosschain Swap`, `Same-chain Swap`, `Send`, `Wrap`, `Unwrap`, `Call`) is **added** at the root. - **`depositAddress`** is now a structured object: `{ address, type: "strict" | "open", depositor, depositTxHash }`. @@ -418,8 +418,7 @@ Every individual change, grouped by request side and response side. | `data.appFeeCurrencyObject` | `data.appFees.currency` | | `data.subsidizedRequest` / `data.subsidizedFee` | `data.feeSponsorship` | | `data.metadata` (catch‑all) | `data.swap` + `data.route` | - | `referrer` (request & response) | — | - | `?includeAuthenticatedData` | automatic for requests created with your API key | + | `referrer` (query parameter) | removed as a filter; still returned in the response when `includeAuthenticatedData=true` | | `?hash` | `term` / `depositTxHash` / `fillTxHash` / `refundTxHash` | | status `delayed` | `depositing` / `submitted` | @@ -440,7 +439,7 @@ Every individual change, grouped by request side and response side. - Point requests at `GET /requests/v3` and send `x-api-key` (now required). Drop `includeAuthenticatedData` and any `referrer` parameter. + Point requests at `GET /requests/v3` and send `x-api-key` (now required). Drop the `referrer` query parameter. Set `includeAuthenticatedData=true` only from a trusted server context to receive authenticated fields (see the note at the end). Stop reading `data.fees.gas` / `feesUsd`. Read the per‑component USD breakdown from `data.fees.quoted` / `data.fees.actual`, and rename the `relay` component to `platform`. @@ -460,5 +459,9 @@ Every individual change, grouped by request side and response side. - Integrator‑only data — revenue share via `platformFee`, un‑redacted pending output, and `refundCurrencyData` — is returned automatically for requests created with your API key. There's no opt‑in flag to set. + Authenticated data (revenue share via `platformFee`, un‑redacted unfilled destination data, and `referrer`) is only returned when you pass `includeAuthenticatedData=true` and authenticate with an API key tied to those requests. + + + `includeAuthenticatedData` gates whether those authenticated fields are returned. If you proxy the Requests API from a public site, force `includeAuthenticatedData=false` on your backend regardless of the incoming value, and only set it `true` from a trusted, authenticated context. + diff --git a/style.css b/style.css index 3f4ad125..7779301f 100644 --- a/style.css +++ b/style.css @@ -395,24 +395,3 @@ padding: 0; } } -/* ── Stronger red/green diff highlighting in code blocks ─────────────────── - Mintlify renders code via Shiki; the default diff line tint is faint. - Boost the contrast for ```diff blocks (and [!code ++]/[!code --] lines). - Tune the rgba alpha values below if you want it stronger/softer. */ -.line.diff.add, -span.line.diff.add, -.line.diff.remove, -span.line.diff.remove { - display: inline-block; - width: 100%; - margin: 0 -1rem; - padding: 0 1rem; -} -.line.diff.add, -span.line.diff.add { - background-color: rgba(46, 160, 67, 0.24) !important; -} -.line.diff.remove, -span.line.diff.remove { - background-color: rgba(248, 81, 73, 0.22) !important; -} From 4aaecaf87186782d95ab8a0ea7d3ec2fcdd6f619 Mon Sep 17 00:00:00 2001 From: Ted Palmer Date: Wed, 8 Jul 2026 16:09:29 -0400 Subject: [PATCH 3/8] Updates --- .../api_guides/migrating-to-requests-v3.mdx | 197 ++++++++++-------- 1 file changed, 114 insertions(+), 83 deletions(-) diff --git a/references/api/api_guides/migrating-to-requests-v3.mdx b/references/api/api_guides/migrating-to-requests-v3.mdx index 011b4a1f..57b89b28 100644 --- a/references/api/api_guides/migrating-to-requests-v3.mdx +++ b/references/api/api_guides/migrating-to-requests-v3.mdx @@ -99,11 +99,11 @@ The same request shown in full for v2 and v3, plus a focused diff of what moved. "id": "0x0000348634...", "status": "success", "user": "0xe7a2052a...", + "sender": "0xE7a205...", "recipient": "0x07082933...", - "referrer": "my-app|user-123", "refundTo": null, "depositAddress": null, - "title": "Crosschain Swap", + "requestType": "Bridge", "data": { "slippageTolerance": "0", "failReason": null, @@ -111,7 +111,6 @@ The same request shown in full for v2 and v3, plus a focused diff of what moved. "failedTxHash": null, "failedTxBlockNumber": null, "failedCallData": null, - "quotedOutputAmount": "10000000000", "usesExternalLiquidity": false, "timeEstimate": 4, "triggeredByFastFill": null, @@ -144,18 +143,22 @@ The same request shown in full for v2 and v3, plus a focused diff of what moved. "actual": { "selectedComponents": ["execution", "swap", "platform", "app"], "capHit": false, "components": { "execution": "…", "swap": "…", "platform": "…", "app": "…" }, "sponsoredTotal": { "amount": "7001090", "amountUsd": "6.999165" }, "userPaysTotal": { "amount": "0", "amountUsd": "0" }, "sponsorPayment": { "amount": "7000949", "address": "0x833589...", "chainId": 8453 } }, "currency": { "chainId": 137, "address": "0x2791bc...", "symbol": "USDC.e", "decimals": 6 } }, - "swap": { - "sender": "0xE7a205...", - "recipient": "0x070829...", - "currencyIn": { "currency": { "chainId": 137, "address": "0x2791bc...", "symbol": "USDC.e", "name": "USDCoin (bridged)", "decimals": 6, "metadata": { "logoURI": "https://...", "verified": true } }, "amount": "10000000000", "amountFormatted": "10000.0", "amountUsd": "9997.600000", "amountUsdCurrent": "9996.000000", "minimumAmount": "10000000000" }, - "currencyOut": { "currency": { "chainId": 8453, "address": "0x833589...", "symbol": "USDC", "name": "USD Coin", "decimals": 6, "metadata": { "logoURI": "https://...", "verified": true } }, "amount": "10000000000", "amountFormatted": "10000.0", "amountUsd": "9997.600000", "amountUsdCurrent": "9996.000000", "minimumAmount": "10000000000" }, - "rate": "1" - }, - "platformFee": null, "route": { - "origin": { "inputCurrency": { "currency": { "chainId": 137, "symbol": "USDC.e", "decimals": 6 }, "amount": "10000000000" }, "outputCurrency": { "currency": { "chainId": 137, "symbol": "USDC.e", "decimals": 6 }, "amount": "10000000000" }, "router": "relay", "includedSwapSources": [] }, - "destination": { "inputCurrency": { "currency": { "chainId": 8453, "symbol": "USDC", "decimals": 6 }, "amount": "10000000000" }, "outputCurrency": { "currency": { "chainId": 8453, "symbol": "USDC", "decimals": 6 }, "amount": "10000000000" }, "router": "relay", "includedSwapSources": [] } + "includedSwapSources": [], + "includedOriginSwapSources": [], + "includedDestinationSwapSources": [], + "quoted": { + "origin": { "inputCurrency": { "currency": { "chainId": 137, "symbol": "USDC.e", "decimals": 6 }, "amount": "10000000000" }, "outputCurrency": { "currency": { "chainId": 137, "symbol": "USDC.e", "decimals": 6 }, "amount": "10000000000" }, "router": "relay" }, + "destination": { "inputCurrency": { "currency": { "chainId": 8453, "symbol": "USDC", "decimals": 6 }, "amount": "10000000000" }, "outputCurrency": { "currency": { "chainId": 8453, "symbol": "USDC", "decimals": 6 }, "amount": "10000000000" }, "router": "relay" } + }, + "actual": { + "rate": "1", + "origin": { "inputCurrency": { "currency": { "chainId": 137, "symbol": "USDC.e", "decimals": 6 }, "amount": "10000000000" }, "outputCurrency": { "currency": { "chainId": 137, "symbol": "USDC.e", "decimals": 6 }, "amount": "10000000000" }, "router": "relay" }, + "destination": { "inputCurrency": { "currency": { "chainId": 8453, "symbol": "USDC", "decimals": 6 }, "amount": "10000000000" }, "outputCurrency": { "currency": { "chainId": 8453, "address": "0x833589...", "symbol": "USDC", "name": "USD Coin", "decimals": 6, "metadata": { "logoURI": "https://...", "verified": true } }, "amount": "10000000000", "amountFormatted": "10000.0", "amountUsd": "9997.600000" }, "router": "relay" } + } }, + "platformFee": null, + "referrer": "my-app|user-123", "refundCurrencyData": null, "externalMetadata": { "moonpayId": null } }, @@ -167,6 +170,7 @@ The same request shown in full for v2 and v3, plus a focused diff of what moved. "deposit": { "origin": { "amount": "10000000000", "chainId": 137, "currency": "0x2791bc...", "depositor": "0xe7a205...", "depository": "0x...", "onchainId": "0x...", "transactionId": "0xcd4d70..." } }, "settlement": { "destination": { "fills": [ { "chainId": 8453, "transactionId": "0x1c0089..." } ], "refunds": [] } } }, + "features": ["app_fees"], "createdAt": "2026-05-25T22:21:11.161Z", "updatedAt": "2026-05-25T22:21:51.291Z" } @@ -178,18 +182,19 @@ The same request shown in full for v2 and v3, plus a focused diff of what moved. "id": "0x0000348634...", "status": "success", "moonpayId": null, // [!code --] + "sender": "0xE7a205...", // [!code ++] promoted from data.metadata.sender "refundTo": null, // [!code ++] - "title": "Crosschain Swap", // [!code ++] - "depositAddress": null, // [!code ++] - "referrer": "my-app|user-123", + "requestType": "Bridge", // [!code ++] + "depositAddress": null, // now an object: { address, type, depositor, depositTxHash } + "referrer": "my-app|user-123", // [!code --] moved to data.referrer (authenticated) + "features": ["app_fees"], // [!code ++] "data": { "failReason": "N/A", // [!code --] "refundFailReason": "N/A", // [!code --] "failReason": null, // [!code ++] "refundFailReason": null, // [!code ++] "subsidizedRequest": true, // [!code --] - "price": "10000000000", // [!code --] - "quotedOutputAmount": "10000000000", // [!code ++] + "price": "10000000000", // [!code --] removed; read data.route.actual.destination.inputCurrency "fees": { "gas": "1160", "fixed": "0", "price": "1999930" }, // [!code --] "feesUsd": { "gas": "0.001159" }, // [!code --] "currency": "usdc", // [!code --] @@ -220,9 +225,13 @@ The same request shown in full for v2 and v3, plus a focused diff of what moved. "outTxs": [ { "hash": "0x1c0089..." } ], // [!code --] "inTxs": [ { "txHash": "0xcd4d70..." } ], // [!code ++] "outTxs": [ { "txHash": "0x1c0089..." } ], // [!code ++] - "metadata": { "currencyIn": {}, "currencyOut": {}, "rate": "1", "route": {} } // [!code --] - "swap": { "currencyIn": {}, "currencyOut": {}, "rate": "1" }, // [!code ++] - "route": { "origin": {}, "destination": {} }, // [!code ++] + "metadata": { "sender": "…", "currencyIn": {}, "currencyOut": {}, "rate": "1", "route": {} }, // [!code --] + "route": { // [!code ++] + "includedSwapSources": [], // [!code ++] + "quoted": { "origin": {}, "destination": {} }, // [!code ++] + "actual": { "rate": "1", "origin": {}, "destination": {} } // [!code ++] + }, // [!code ++] + "referrer": "my-app|user-123", // [!code ++] authenticated; moved from root "externalMetadata": { "moonpayId": null } // [!code ++] } } @@ -242,10 +251,10 @@ Every individual change, grouped by request side and response side. - ```diff - GET /requests/v3 - Headers: - + x-api-key: # now required + ```bash + GET /requests/v3 + Headers: + x-api-key: # now required [!code ++] ``` The `x-api-key` request header is now required. Every request authenticates against an active API key. See [API Keys](/references/api/api-keys) for details. @@ -259,7 +268,7 @@ Every individual change, grouped by request side and response side. | **Search** | `term` (request id, wallet, deposit address, every tx hash), `id`, `orderId`, `depositTxHash`, `fillTxHash`, `refundTxHash` | | **Chain** | `originChainId`, `destinationChainId`, `chainId` (either direction), `privateChainsToInclude` | | **Address** | `user`, `depositAddress`, `recipient` | - | **Status / routing** | `status`, `failReason`, `refundFailReason`, `apiKey`, `title` | + | **Status / routing** | `status`, `failReason`, `refundFailReason`, `apiKey`, `requestType` | | **Currency** | `currencyInChainId`, `currencyOutChainId`, `currencyInAddress`, `currencyOutAddress` | | **Ranges** | `startTimestamp`, `endTimestamp`, `startBlock`, `endBlock`, `amountUsdMin`/`Max`, `appFeesAmountUsdMin`/`Max`, `fillTimeMin`/`Max` | | **Other** | `features`, `includeChildRequests`, `filters` (AND/OR), `sortBy`, `sortDirection`, `includeAuthenticatedData` | @@ -292,102 +301,119 @@ Every individual change, grouped by request side and response side. The response envelope now includes a `total`, and `continuation` is an opaque cursor you pass back to fetch the next page. `limit` defaults to 20 and is capped at **50**. - ```diff - - // v2: offset-style paging, no total - + "total": 12345, - + "continuation": "eyJ..." // opaque cursor, pass back as ?continuation= + ```jsonc + // v2: offset-style paging, no total [!code --] + "total": 12345, // [!code ++] + "continuation": "eyJ..." // opaque cursor, pass back as ?continuation= [!code ++] ``` The `currency` (string) + `currencyObject` (object) duality is removed everywhere, along with `feeCurrency`/`feeCurrencyObject` and `appFeeCurrencyObject`. Every currency is a single object: `{ chainId, address, symbol, name, decimals, metadata }`. Amount objects carry that currency plus `amount`, `amountFormatted`, `amountUsd`, and where relevant `amountUsdCurrent`, `minimumAmount`. - ```diff - - "currency": "usdc", - - "currencyObject": { "chainId": 137, "symbol": "USDC", "decimals": 6 } - + // read the currency object directly off the amount, e.g. data.swap.currencyIn.currency + ```jsonc + "currency": "usdc", // [!code --] + "currencyObject": { "chainId": 137, "symbol": "USDC", "decimals": 6 } // [!code --] + // read the currency object directly off the amount, [!code ++] + // e.g. data.route.actual.origin.inputCurrency.currency [!code ++] ``` `data.expandedPriceImpact` is renamed to **`data.fees`** (and the old wei `data.fees` / `data.feesUsd` are removed). Each phase (`quoted`, `actual`) breaks fees into `swap`, `execution`, `platform`, `app`, and `sponsored`, with the shared currency hoisted to `data.fees.currency`. The `relay` component is renamed to **`platform`**, and per‑component values now include `amount` and `amountFormatted` in addition to `usd`. - ```diff - - "expandedPriceImpact": { "quoted": { "swap": { "usd": "-1.99" }, "relay": { "usd": "0" } } } - + "fees": { - + "quoted": { "swap": { "usd": "-1.99", "amount": "...", "amountFormatted": "..." }, "platform": { "usd": "0" } }, - + "actual": { "...": "..." }, - + "currency": { "symbol": "USDC.e" } - + } + ```jsonc + "expandedPriceImpact": { "quoted": { "swap": { "usd": "-1.99" }, "relay": { "usd": "0" } } } // [!code --] + "fees": { // [!code ++] + "quoted": { "swap": { "usd": "-1.99", "amount": "...", "amountFormatted": "..." }, "platform": { "usd": "0" } }, // [!code ++] + "actual": { "...": "..." }, // [!code ++] + "currency": { "symbol": "USDC.e" } // [!code ++] + } // [!code ++] ``` `data.subsidizedRequest` and `data.subsidizedFee` are removed. `data.feeSponsorship` is now the only sponsorship source — determine whether a request was sponsored from `feeSponsorship.{quoted,actual}.sponsoredTotal.amountUsd`. The `relay` bucket is renamed to **`platform`**, the shared `currency` is hoisted to `feeSponsorship.currency`, and the `actual` phase gains a `sponsorPayment` object. - ```diff - - "subsidizedRequest": true, - - "subsidizedFee": { "amountUsd": "6.99" }, - "feeSponsorship": { - - "quoted": { "selectedComponents": ["execution","swap","relay","app"], "components": { "relay": {} } } - + "quoted": { "selectedComponents": ["execution","swap","platform","app"], "components": { "platform": {} } }, - + "actual": { "sponsorPayment": { "amount": "...", "chainId": 8453 } }, - + "currency": { "symbol": "USDC.e" } - } + ```jsonc + "subsidizedRequest": true, // [!code --] + "subsidizedFee": { "amountUsd": "6.99" }, // [!code --] + "feeSponsorship": { + "quoted": { "selectedComponents": ["execution","swap","relay","app"], "components": { "relay": {} } } // [!code --] + "quoted": { "selectedComponents": ["execution","swap","platform","app"], "components": { "platform": {} } }, // [!code ++] + "actual": { "sponsorPayment": { "amount": "...", "chainId": 8453 } }, // [!code ++] + "currency": { "symbol": "USDC.e" } // [!code ++] + } ``` The parallel `appFees` (quoted) and `paidAppFees` (actual) arrays are consolidated into one object with explicit `quoted` / `actual` keys and a hoisted `currency`. - ```diff - - "appFees": [ { "bps": "5", "amount": "5000000" } ], - - "paidAppFees": [ { "bps": "5", "amount": "5000000", "amountUsd": "4.99" } ], - + "appFees": { - + "quoted": [ { "bps": "5", "amount": "5000000" } ], - + "actual": [ { "bps": "5", "amount": "5000000", "amountUsd": "4.99" } ], - + "currency": { "symbol": "USDC.e" } - + } + ```jsonc + "appFees": [ { "bps": "5", "amount": "5000000" } ], // [!code --] + "paidAppFees": [ { "bps": "5", "amount": "5000000", "amountUsd": "4.99" } ], // [!code --] + "appFees": { // [!code ++] + "quoted": [ { "bps": "5", "amount": "5000000" } ], // [!code ++] + "actual": [ { "bps": "5", "amount": "5000000", "amountUsd": "4.99" } ], // [!code ++] + "currency": { "symbol": "USDC.e" } // [!code ++] + } // [!code ++] ``` - - The `data.metadata` catch‑all is removed. Its swap fields move to **`data.swap`** (`sender`, `recipient`, `currencyIn`, `currencyOut`, `rate`, `currencyGasTopup`) and the routing info moves to **`data.route`** (`origin` / `destination` with `inputCurrency`, `outputCurrency`, `router`, `includedSwapSources`). + + The `data.metadata` catch‑all is removed. `sender` is promoted to the **root** (next to `recipient`), and everything else moves into **`data.route`**, which now has two phases: + + - `data.route.quoted` — the route as quoted at request time. + - `data.route.actual` — what actually executed. Carries `rate`, and `actual` falls back to `quoted` when there's no execution data yet (e.g. same‑chain swaps). + + Each phase has `origin` and `destination` sides, and each side has `inputCurrency` / `outputCurrency` (each a full amount object) plus `router`. `includedSwapSources` / `includedOriginSwapSources` / `includedDestinationSwapSources` are hoisted to the top of `data.route`. + + There is **no `data.swap`** and **no `data.quotedOutputAmount`** — read amounts from the route instead: + + - Amount deposited: `data.route.actual.origin.inputCurrency` (→ `quoted`). + - Amount received: `data.route.actual.destination.outputCurrency` (→ `quoted`). For same‑chain swaps there is no destination side, so fall back to `origin.outputCurrency`. - ```diff - - "metadata": { "currencyIn": {}, "currencyOut": {}, "rate": "1", "route": {} } - + "swap": { "currencyIn": {}, "currencyOut": {}, "rate": "1" }, - + "route": { "origin": {}, "destination": {} } + ```jsonc + "metadata": { "sender": "…", "currencyIn": {}, "currencyOut": {}, "rate": "1", "route": {} } // [!code --] + // sender → promoted to the root [!code ++] + "route": { // [!code ++] + "includedSwapSources": [], // [!code ++] + "quoted": { "origin": {}, "destination": {} }, // [!code ++] + "actual": { "rate": "1", "origin": {}, "destination": {} } // [!code ++] + } // [!code ++] ``` Inside `inTxs[]` and `outTxs[]`, the `hash` field is renamed to `txHash`. The array names themselves are unchanged. - ```diff - - "inTxs": [ { "hash": "0xcd4d70..." } ], - - "outTxs": [ { "hash": "0x1c0089..." } ] - + "inTxs": [ { "txHash": "0xcd4d70..." } ], - + "outTxs": [ { "txHash": "0x1c0089..." } ] + ```jsonc + "inTxs": [ { "hash": "0xcd4d70..." } ], // [!code --] + "outTxs": [ { "hash": "0x1c0089..." } ] // [!code --] + "inTxs": [ { "txHash": "0xcd4d70..." } ], // [!code ++] + "outTxs": [ { "txHash": "0x1c0089..." } ] // [!code ++] ``` The response `status` enum is now `pending`, `waiting`, `depositing`, `submitted`, `success`, `failure`, `refund`. `depositing` and `submitted` are new; the v2 `delayed` value is gone. The `status` **filter** accepts `success`, `failure`, `refund`, `pending`, `depositing`. - ```diff - - status ∈ { pending, waiting, delayed, success, failure, refund } - + status ∈ { pending, waiting, depositing, submitted, success, failure, refund } + ```jsonc + status ∈ { pending, waiting, delayed, success, failure, refund } // [!code --] + status ∈ { pending, waiting, depositing, submitted, success, failure, refund } // [!code ++] ``` - `moonpayId` moves from the root to **`data.externalMetadata.moonpayId`**. - - `referrer` is no longer a query parameter, but it's still returned in the response — **only when `includeAuthenticatedData=true`**. + - `sender` is **promoted to the root** (next to `recipient`); it previously lived in `data.metadata.sender`. + - `referrer` moves into **`data.referrer`** and is returned **only when `includeAuthenticatedData=true`**. It's also no longer a query parameter. - **`refundTo`** (refund target for deposit‑address transactions) is **added** at the root. - - **`title`** (the request type: `Bridge`, `Crosschain Swap`, `Same-chain Swap`, `Send`, `Wrap`, `Unwrap`, `Call`) is **added** at the root. + - **`requestType`** (`Bridge`, `Crosschain Swap`, `Same-chain Swap`, `Send`, `Wrap`, `Unwrap`, `Call`) is **added** at the root. + - **`features`** (e.g. `gasless_execution`, `fast_fill`, `gas_top_up`, `app_fees`, `deposit_address`) is **added** at the root. - **`depositAddress`** is now a structured object: `{ address, type: "strict" | "open", depositor, depositTxHash }`. - - `data.price` → **`data.quotedOutputAmount`** (the amount the solver committed to send at solve time — distinct from the actual received amount in `data.swap.currencyOut.amount`). + - `data.price` is **removed** — read the quoted output amount from `data.route.actual.destination.inputCurrency` (distinct from the actual received amount in `data.route.actual.destination.outputCurrency`). - `failReason` / `refundFailReason` use **`null`** instead of the string `"N/A"`. @@ -399,9 +425,10 @@ Every individual change, grouped by request side and response side. | v2 | v3 | | --- | --- | | `data.expandedPriceImpact` | `data.fees` (component `relay` → `platform`) | - | `data.price` | `data.quotedOutputAmount` | - | `data.metadata.{currencyIn,currencyOut,sender,recipient,rate,currencyGasTopup}` | `data.swap.*` | - | `data.metadata.route` | `data.route` | + | `data.metadata.sender` | `sender` (root) | + | `data.metadata.recipient` | `recipient` (root) | + | `data.metadata.{currencyIn,currencyOut,rate,currencyGasTopup}` | `data.route.{quoted,actual}.*` | + | `data.metadata.route` | `data.route.{quoted,actual}` | | `data.appFees` (quoted) + `data.paidAppFees` (actual) | `data.appFees.{quoted,actual,currency}` | | `inTxs[].hash` / `outTxs[].hash` | `inTxs[].txHash` / `outTxs[].txHash` | | `feeSponsorship…components.relay` | `feeSponsorship…components.platform` | @@ -417,7 +444,8 @@ Every individual change, grouped by request side and response side. | `data.feeCurrency` / `data.feeCurrencyObject` | currency hoisted into fee objects | | `data.appFeeCurrencyObject` | `data.appFees.currency` | | `data.subsidizedRequest` / `data.subsidizedFee` | `data.feeSponsorship` | - | `data.metadata` (catch‑all) | `data.swap` + `data.route` | + | `data.metadata` (catch‑all) | `data.route.{quoted,actual}` (`sender` promoted to root) | + | `data.price` | read `data.route.actual.destination.inputCurrency` | | `referrer` (query parameter) | removed as a filter; still returned in the response when `includeAuthenticatedData=true` | | `?hash` | `term` / `depositTxHash` / `fillTxHash` / `refundTxHash` | | status `delayed` | `depositing` / `submitted` | @@ -427,8 +455,11 @@ Every individual change, grouped by request side and response side. | --- | --- | | `total` (envelope) | total matching the current filters | | `continuation` cursor | opaque pagination cursor | - | `title` | request type | + | `requestType` | request type (`Bridge`, `Crosschain Swap`, `Same-chain Swap`, `Send`, `Wrap`, `Unwrap`, `Call`) | + | `sender` (root) | promoted from `data.metadata.sender` | + | `features` (root) | request feature flags (`gasless_execution`, `fast_fill`, `app_fees`, …) | | `refundTo` | refund target for deposit‑address flows | + | `data.route.actual` | executed route (with `rate`); falls back to `quoted` | | `data.externalMetadata` | partner correlation IDs (e.g. `moonpayId`) | | `feeSponsorship.actual.sponsorPayment` | what the sponsor actually paid | | broad filter/sort surface | see [Filtering, search & sorting](#what-changed) | @@ -441,11 +472,11 @@ Every individual change, grouped by request side and response side. Point requests at `GET /requests/v3` and send `x-api-key` (now required). Drop the `referrer` query parameter. Set `includeAuthenticatedData=true` only from a trusted server context to receive authenticated fields (see the note at the end). - + Stop reading `data.fees.gas` / `feesUsd`. Read the per‑component USD breakdown from `data.fees.quoted` / `data.fees.actual`, and rename the `relay` component to `platform`. - - Replace `data.metadata.currencyIn/out/...` with `data.swap.*` and `data.metadata.route` with `data.route`. Drop `currency`/`currencyObject` string handling — read the single currency object. + + Replace `data.metadata.*` reads: `sender` is now at the root, and currencies/rate come from `data.route.{quoted,actual}` (prefer `actual`, fall back to `quoted`). Read the deposited amount from `route.actual.origin.inputCurrency` and the received amount from `route.actual.destination.outputCurrency` (fall back to `origin.outputCurrency` for same‑chain swaps). Drop `currency`/`currencyObject` string handling — read the single currency object. Read `data.appFees.quoted` / `data.appFees.actual`. Replace `subsidizedRequest`/`subsidizedFee` with `data.feeSponsorship`, and rename its `relay` bucket to `platform`. From 964d32137c5914d7177e67661a32f724fb52dace Mon Sep 17 00:00:00 2001 From: Ted Palmer Date: Wed, 8 Jul 2026 16:15:25 -0400 Subject: [PATCH 4/8] latest --- .../api/api_guides/migrating-to-requests-v3.mdx | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/references/api/api_guides/migrating-to-requests-v3.mdx b/references/api/api_guides/migrating-to-requests-v3.mdx index 57b89b28..c90db674 100644 --- a/references/api/api_guides/migrating-to-requests-v3.mdx +++ b/references/api/api_guides/migrating-to-requests-v3.mdx @@ -269,7 +269,7 @@ Every individual change, grouped by request side and response side. | **Chain** | `originChainId`, `destinationChainId`, `chainId` (either direction), `privateChainsToInclude` | | **Address** | `user`, `depositAddress`, `recipient` | | **Status / routing** | `status`, `failReason`, `refundFailReason`, `apiKey`, `requestType` | - | **Currency** | `currencyInChainId`, `currencyOutChainId`, `currencyInAddress`, `currencyOutAddress` | + | **Currency** | `currencyInChainId`, `currencyOutChainId`, `currencyInAddress`, `currencyOutAddress`, `currencyInSymbol`, `currencyOutSymbol` | | **Ranges** | `startTimestamp`, `endTimestamp`, `startBlock`, `endBlock`, `amountUsdMin`/`Max`, `appFeesAmountUsdMin`/`Max`, `fillTimeMin`/`Max` | | **Other** | `features`, `includeChildRequests`, `filters` (AND/OR), `sortBy`, `sortDirection`, `includeAuthenticatedData` | @@ -298,12 +298,11 @@ Every individual change, grouped by request side and response side. ### Response fields - - The response envelope now includes a `total`, and `continuation` is an opaque cursor you pass back to fetch the next page. `limit` defaults to 20 and is capped at **50**. + + `continuation` is an opaque cursor you pass back to fetch the next page. `limit` defaults to 20 and is capped at **50**. ```jsonc - // v2: offset-style paging, no total [!code --] - "total": 12345, // [!code ++] + // v2: offset-style paging [!code --] "continuation": "eyJ..." // opaque cursor, pass back as ?continuation= [!code ++] ``` @@ -453,7 +452,6 @@ Every individual change, grouped by request side and response side. | Added in v3 | Notes | | --- | --- | - | `total` (envelope) | total matching the current filters | | `continuation` cursor | opaque pagination cursor | | `requestType` | request type (`Bridge`, `Crosschain Swap`, `Same-chain Swap`, `Send`, `Wrap`, `Unwrap`, `Call`) | | `sender` (root) | promoted from `data.metadata.sender` | @@ -485,7 +483,7 @@ Every individual change, grouped by request side and response side. Rename `inTxs[].hash` / `outTxs[].hash` to `txHash`. Handle the new `depositing` / `submitted` statuses (and remove `delayed`). Treat `failReason` / `refundFailReason` as `null` rather than `"N/A"`. - Replace separate `user`/`hash`/`id` lookups with a single `term` search where it fits. Use `total` for counts and pass `continuation` back for the next page (`limit` max 50). + Replace separate `user`/`hash`/`id` lookups with a single `term` search where it fits. Paginate by passing `continuation` back for the next page (`limit` max 50). From c05b42732184f3c1cf7bbdd81f1981696b62e262 Mon Sep 17 00:00:00 2001 From: Ted Palmer Date: Wed, 8 Jul 2026 21:13:47 -0400 Subject: [PATCH 5/8] Fixes --- .../api_guides/migrating-to-requests-v3.mdx | 19 ++++++------------- references/api/get-requests.mdx | 2 +- 2 files changed, 7 insertions(+), 14 deletions(-) diff --git a/references/api/api_guides/migrating-to-requests-v3.mdx b/references/api/api_guides/migrating-to-requests-v3.mdx index c90db674..41fc7bb2 100644 --- a/references/api/api_guides/migrating-to-requests-v3.mdx +++ b/references/api/api_guides/migrating-to-requests-v3.mdx @@ -279,11 +279,14 @@ Every individual change, grouped by request side and response side. **Sorting.** `sortBy` accepts `createdAt` (default), `updatedAt`, or `amountUsd`. `sortDirection` is `asc` or `desc` (defaults to `desc` for time fields, `asc` for `amountUsd`). - **Advanced filtering (AND / OR composition).** The `filters` parameter takes a JSON‑encoded array of groups. Fields **within** a group are AND'd; the groups themselves are OR'd. Top‑level parameters still apply. + **Advanced filtering (AND / OR / negation).** The `filters` parameter takes a JSON‑encoded array of groups. Fields **within** a group are AND'd; the groups themselves are OR'd. Any key can be negated with a `not:` prefix, and a field's value may be an array (OR within that field). Top‑level parameters still apply. ```bash # "(depositAddress=0xabc AND originChainId=8453) OR (depositAddress=0x123 AND originChainId=1)" GET /requests/v3?filters=[{"depositAddress":"0xabc","originChainId":8453},{"depositAddress":"0x123","originChainId":1}] + + # negation + array value: everything except failures and refunds + GET /requests/v3?filters=[{"not:status":["failure","refund"]}] ``` OR groups support identity, address, chain, currency, and status‑style fields. Range filters and `features` are top‑level only. @@ -298,15 +301,6 @@ Every individual change, grouped by request side and response side. ### Response fields - - `continuation` is an opaque cursor you pass back to fetch the next page. `limit` defaults to 20 and is capped at **50**. - - ```jsonc - // v2: offset-style paging [!code --] - "continuation": "eyJ..." // opaque cursor, pass back as ?continuation= [!code ++] - ``` - - The `currency` (string) + `currencyObject` (object) duality is removed everywhere, along with `feeCurrency`/`feeCurrencyObject` and `appFeeCurrencyObject`. Every currency is a single object: `{ chainId, address, symbol, name, decimals, metadata }`. Amount objects carry that currency plus `amount`, `amountFormatted`, `amountUsd`, and where relevant `amountUsdCurrent`, `minimumAmount`. @@ -452,7 +446,6 @@ Every individual change, grouped by request side and response side. | Added in v3 | Notes | | --- | --- | - | `continuation` cursor | opaque pagination cursor | | `requestType` | request type (`Bridge`, `Crosschain Swap`, `Same-chain Swap`, `Send`, `Wrap`, `Unwrap`, `Call`) | | `sender` (root) | promoted from `data.metadata.sender` | | `features` (root) | request feature flags (`gasless_execution`, `fast_fill`, `app_fees`, …) | @@ -482,8 +475,8 @@ Every individual change, grouped by request side and response side. Rename `inTxs[].hash` / `outTxs[].hash` to `txHash`. Handle the new `depositing` / `submitted` statuses (and remove `delayed`). Treat `failReason` / `refundFailReason` as `null` rather than `"N/A"`. - - Replace separate `user`/`hash`/`id` lookups with a single `term` search where it fits. Paginate by passing `continuation` back for the next page (`limit` max 50). + + Replace separate `user`/`hash`/`id` lookups with a single `term` search where it fits, and take advantage of the new filter/sort parameters. Pagination is unchanged — keep passing `continuation` back for the next page (`limit` max 50). diff --git a/references/api/get-requests.mdx b/references/api/get-requests.mdx index f6340217..6a4a98f1 100644 --- a/references/api/get-requests.mdx +++ b/references/api/get-requests.mdx @@ -1,5 +1,5 @@ --- title: "Get Requests" description: "This API returns all the cross-chain transactions." -openapi: get /requests/v2 +openapi: get /requests/v3 --- From 15c8f23a94b0eea538c436a791661a9508127535 Mon Sep 17 00:00:00 2001 From: Ted Palmer Date: Thu, 9 Jul 2026 11:06:20 -0400 Subject: [PATCH 6/8] Feedback --- docs.json | 1 + references/api/api_core_concepts/fees.mdx | 4 +-- .../api_guides/migrating-to-requests-v3.mdx | 34 +++++++++---------- references/api/get-requests-v2.mdx | 9 +++++ 4 files changed, 28 insertions(+), 20 deletions(-) create mode 100644 references/api/get-requests-v2.mdx diff --git a/docs.json b/docs.json index 757dff50..d30b60a1 100644 --- a/docs.json +++ b/docs.json @@ -161,6 +161,7 @@ { "group": "Deprecated", "pages": [ + "references/api/get-requests-v2", "references/api/get-price", "references/api/get-config", "references/api/get-intents-status", diff --git a/references/api/api_core_concepts/fees.mdx b/references/api/api_core_concepts/fees.mdx index 3fbf0058..f2389630 100644 --- a/references/api/api_core_concepts/fees.mdx +++ b/references/api/api_core_concepts/fees.mdx @@ -135,7 +135,7 @@ When displaying fees to users, we recommend mapping the `data.fees` fields as fo -In the quote API and [`GET /requests/v2`](/references/api/get-requests), this same breakdown is returned as the `expandedPriceImpact` object, and the **platform** component is named **relay**. +In the quote API and [`GET /requests/v2`](/references/api/get-requests-v2), this same breakdown is returned as the `expandedPriceImpact` object, and the **platform** component is named **relay**. ## Fee Sponsorship @@ -151,7 +151,7 @@ See the [Fee Sponsorship Doc](/features/fee-sponsorship) for setup details. ## Deprecated: Fees Object -The `fees` object is deprecated. It is still returned from the quote API and the [`GET /requests/v2`](/references/api/get-requests) API for backwards compatibility, but it only reports Relay-related fees and does not reflect the full cost of a request. Do not rely on it for new integrations. +The `fees` object is deprecated. It is still returned from the quote API and the [`GET /requests/v2`](/references/api/get-requests-v2) API for backwards compatibility, but it only reports Relay-related fees and does not reflect the full cost of a request. Do not rely on it for new integrations. To understand or display the complete fee breakdown of a request, use the [`data.fees`](#fees-in-the-api) object in `GET /requests/v3` (or `expandedPriceImpact` in the quote API and `GET /requests/v2`) instead, which covers execution, swap, platform, app, and sponsored fees. diff --git a/references/api/api_guides/migrating-to-requests-v3.mdx b/references/api/api_guides/migrating-to-requests-v3.mdx index 41fc7bb2..54f82725 100644 --- a/references/api/api_guides/migrating-to-requests-v3.mdx +++ b/references/api/api_guides/migrating-to-requests-v3.mdx @@ -240,7 +240,7 @@ The same request shown in full for v2 and v3, plus a focused diff of what moved. - **`data.fees` has changed meaning.** The key `fees` is reused for a different shape. In v2, `data.fees` was raw wei (`gas`/`fixed`/`price`/`gateway`). In v3 that object is removed, and `data.fees` now holds the per‑component USD breakdown that v2 called `expandedPriceImpact`. Code reading `data.fees.gas` will break — read `data.fees.quoted` / `data.fees.actual` instead. + **`data.fees` has changed meaning.** The key `fees` is reused for a different shape. In v2, `data.fees` was raw wei (`gas`/`fixed`/`price`/`gateway`). In v3 that object is removed, and `data.fees` now holds the per-component USD breakdown that v2 called `expandedPriceImpact`. Code reading `data.fees.gas` will break — read `data.fees.quoted` / `data.fees.actual` instead. ## What changed @@ -274,12 +274,12 @@ Every individual change, grouped by request side and response side. | **Other** | `features`, `includeChildRequests`, `filters` (AND/OR), `sortBy`, `sortDirection`, `includeAuthenticatedData` | - `term` is a single unified search across request id, wallet, deposit address, and every transaction hash (deposit, fill, refund, failed, chain‑entry). It replaces the v2 pattern of running separate `user` / `hash` / `id` lookups and merging the results. + `term` is a single unified search across request id, wallet, deposit address, and every transaction hash (deposit, fill, refund, failed, chain-entry). It replaces the v2 pattern of running separate `user` / `hash` / `id` lookups and merging the results. **Sorting.** `sortBy` accepts `createdAt` (default), `updatedAt`, or `amountUsd`. `sortDirection` is `asc` or `desc` (defaults to `desc` for time fields, `asc` for `amountUsd`). - **Advanced filtering (AND / OR / negation).** The `filters` parameter takes a JSON‑encoded array of groups. Fields **within** a group are AND'd; the groups themselves are OR'd. Any key can be negated with a `not:` prefix, and a field's value may be an array (OR within that field). Top‑level parameters still apply. + **Advanced filtering (AND / OR / negation).** The `filters` parameter takes a JSON-encoded array of groups. Fields **within** a group are AND'd; the groups themselves are OR'd. Any key can be negated with a `not:` prefix, and a field's value may be an array (OR within that field). Top-level parameters still apply. ```bash # "(depositAddress=0xabc AND originChainId=8453) OR (depositAddress=0x123 AND originChainId=1)" @@ -289,7 +289,7 @@ Every individual change, grouped by request side and response side. GET /requests/v3?filters=[{"not:status":["failure","refund"]}] ``` - OR groups support identity, address, chain, currency, and status‑style fields. Range filters and `features` are top‑level only. + OR groups support identity, address, chain, currency, and status-style fields. Range filters and `features` are top-level only. **Removed & changed parameters.** - `hash` is removed; use `term`, or the targeted `depositTxHash` / `fillTxHash` / `refundTxHash`. @@ -313,7 +313,7 @@ Every individual change, grouped by request side and response side. - `data.expandedPriceImpact` is renamed to **`data.fees`** (and the old wei `data.fees` / `data.feesUsd` are removed). Each phase (`quoted`, `actual`) breaks fees into `swap`, `execution`, `platform`, `app`, and `sponsored`, with the shared currency hoisted to `data.fees.currency`. The `relay` component is renamed to **`platform`**, and per‑component values now include `amount` and `amountFormatted` in addition to `usd`. + `data.expandedPriceImpact` is renamed to **`data.fees`** (and the old wei `data.fees` / `data.feesUsd` are removed). Each phase (`quoted`, `actual`) breaks fees into `swap`, `execution`, `platform`, `app`, and `sponsored`, with the shared currency hoisted to `data.fees.currency`. The `relay` component is renamed to **`platform`**, and per-component values now include `amount` and `amountFormatted` in addition to `usd`. ```jsonc "expandedPriceImpact": { "quoted": { "swap": { "usd": "-1.99" }, "relay": { "usd": "0" } } } // [!code --] @@ -355,17 +355,17 @@ Every individual change, grouped by request side and response side. - The `data.metadata` catch‑all is removed. `sender` is promoted to the **root** (next to `recipient`), and everything else moves into **`data.route`**, which now has two phases: + The `data.metadata` catch-all is removed. `sender` is promoted to the **root** (next to `recipient`), and everything else moves into **`data.route`**, which now has two phases: - `data.route.quoted` — the route as quoted at request time. - - `data.route.actual` — what actually executed. Carries `rate`, and `actual` falls back to `quoted` when there's no execution data yet (e.g. same‑chain swaps). + - `data.route.actual` — what actually executed. Carries `rate`, and `actual` falls back to `quoted` when there's no execution data yet (e.g. same-chain swaps). Each phase has `origin` and `destination` sides, and each side has `inputCurrency` / `outputCurrency` (each a full amount object) plus `router`. `includedSwapSources` / `includedOriginSwapSources` / `includedDestinationSwapSources` are hoisted to the top of `data.route`. There is **no `data.swap`** and **no `data.quotedOutputAmount`** — read amounts from the route instead: - Amount deposited: `data.route.actual.origin.inputCurrency` (→ `quoted`). - - Amount received: `data.route.actual.destination.outputCurrency` (→ `quoted`). For same‑chain swaps there is no destination side, so fall back to `origin.outputCurrency`. + - Amount received: `data.route.actual.destination.outputCurrency` (→ `quoted`). For same-chain swaps there is no destination side, so fall back to `origin.outputCurrency`. ```jsonc "metadata": { "sender": "…", "currencyIn": {}, "currencyOut": {}, "rate": "1", "route": {} } // [!code --] @@ -402,7 +402,7 @@ Every individual change, grouped by request side and response side. - `moonpayId` moves from the root to **`data.externalMetadata.moonpayId`**. - `sender` is **promoted to the root** (next to `recipient`); it previously lived in `data.metadata.sender`. - `referrer` moves into **`data.referrer`** and is returned **only when `includeAuthenticatedData=true`**. It's also no longer a query parameter. - - **`refundTo`** (refund target for deposit‑address transactions) is **added** at the root. + - **`refundTo`** (refund target for deposit-address transactions) is **added** at the root. - **`requestType`** (`Bridge`, `Crosschain Swap`, `Same-chain Swap`, `Send`, `Wrap`, `Unwrap`, `Call`) is **added** at the root. - **`features`** (e.g. `gasless_execution`, `fast_fill`, `gas_top_up`, `app_fees`, `deposit_address`) is **added** at the root. - **`depositAddress`** is now a structured object: `{ address, type: "strict" | "open", depositor, depositTxHash }`. @@ -431,13 +431,13 @@ Every individual change, grouped by request side and response side. | Removed in v3 | Replacement | | --- | --- | - | `data.fees` (wei `gas`/`fixed`/`price`/`gateway`) | `data.fees` (now USD price‑impact) | + | `data.fees` (wei `gas`/`fixed`/`price`/`gateway`) | `data.fees` (now USD price-impact) | | `data.feesUsd` | `data.fees` | | `data.currency` / `data.currencyObject` | currency object on each amount | | `data.feeCurrency` / `data.feeCurrencyObject` | currency hoisted into fee objects | | `data.appFeeCurrencyObject` | `data.appFees.currency` | | `data.subsidizedRequest` / `data.subsidizedFee` | `data.feeSponsorship` | - | `data.metadata` (catch‑all) | `data.route.{quoted,actual}` (`sender` promoted to root) | + | `data.metadata` (catch-all) | `data.route.{quoted,actual}` (`sender` promoted to root) | | `data.price` | read `data.route.actual.destination.inputCurrency` | | `referrer` (query parameter) | removed as a filter; still returned in the response when `includeAuthenticatedData=true` | | `?hash` | `term` / `depositTxHash` / `fillTxHash` / `refundTxHash` | @@ -449,7 +449,7 @@ Every individual change, grouped by request side and response side. | `requestType` | request type (`Bridge`, `Crosschain Swap`, `Same-chain Swap`, `Send`, `Wrap`, `Unwrap`, `Call`) | | `sender` (root) | promoted from `data.metadata.sender` | | `features` (root) | request feature flags (`gasless_execution`, `fast_fill`, `app_fees`, …) | - | `refundTo` | refund target for deposit‑address flows | + | `refundTo` | refund target for deposit-address flows | | `data.route.actual` | executed route (with `rate`); falls back to `quoted` | | `data.externalMetadata` | partner correlation IDs (e.g. `moonpayId`) | | `feeSponsorship.actual.sponsorPayment` | what the sponsor actually paid | @@ -464,10 +464,10 @@ Every individual change, grouped by request side and response side. Point requests at `GET /requests/v3` and send `x-api-key` (now required). Drop the `referrer` query parameter. Set `includeAuthenticatedData=true` only from a trusted server context to receive authenticated fields (see the note at the end). - Stop reading `data.fees.gas` / `feesUsd`. Read the per‑component USD breakdown from `data.fees.quoted` / `data.fees.actual`, and rename the `relay` component to `platform`. + Stop reading `data.fees.gas` / `feesUsd`. Read the per-component USD breakdown from `data.fees.quoted` / `data.fees.actual`, and rename the `relay` component to `platform`. - Replace `data.metadata.*` reads: `sender` is now at the root, and currencies/rate come from `data.route.{quoted,actual}` (prefer `actual`, fall back to `quoted`). Read the deposited amount from `route.actual.origin.inputCurrency` and the received amount from `route.actual.destination.outputCurrency` (fall back to `origin.outputCurrency` for same‑chain swaps). Drop `currency`/`currencyObject` string handling — read the single currency object. + Replace `data.metadata.*` reads: `sender` is now at the root, and currencies/rate come from `data.route.{quoted,actual}` (prefer `actual`, fall back to `quoted`). Read the deposited amount from `route.actual.origin.inputCurrency` and the received amount from `route.actual.destination.outputCurrency` (fall back to `origin.outputCurrency` for same-chain swaps). Drop `currency`/`currencyObject` string handling — read the single currency object. Read `data.appFees.quoted` / `data.appFees.actual`. Replace `subsidizedRequest`/`subsidizedFee` with `data.feeSponsorship`, and rename its `relay` bucket to `platform`. @@ -481,9 +481,7 @@ Every individual change, grouped by request side and response side. - Authenticated data (revenue share via `platformFee`, un‑redacted unfilled destination data, and `referrer`) is only returned when you pass `includeAuthenticatedData=true` and authenticate with an API key tied to those requests. + Authenticated data is only returned when you pass `includeAuthenticatedData=true` and authenticate with an API key tied to those requests. - - `includeAuthenticatedData` gates whether those authenticated fields are returned. If you proxy the Requests API from a public site, force `includeAuthenticatedData=false` on your backend regardless of the incoming value, and only set it `true` from a trusted, authenticated context. - + diff --git a/references/api/get-requests-v2.mdx b/references/api/get-requests-v2.mdx new file mode 100644 index 00000000..d1fe4f42 --- /dev/null +++ b/references/api/get-requests-v2.mdx @@ -0,0 +1,9 @@ +--- +title: "Get Requests (v2)" +description: "Deprecated. Returns cross-chain transactions. Use GET /requests/v3 for new integrations." +openapi: get /requests/v2 +--- + + + `GET /requests/v2` is deprecated. New integrations should use [`GET /requests/v3`](/references/api/get-requests), which requires authentication and offers a richer filter surface and a cleaner response. See the [migration guide](/references/api/api_guides/migrating-to-requests-v3) for what changed and how to upgrade. + From 1eebb2fbbd48d29940dc895853b0abf3adc35895 Mon Sep 17 00:00:00 2001 From: Ted Palmer Date: Wed, 22 Jul 2026 10:29:12 -0400 Subject: [PATCH 7/8] Add sunset timeline --- .../api_guides/migrating-to-requests-v3.mdx | 26 ++++++++++++++++--- references/api/changelog.mdx | 6 +++++ references/api/get-requests-v2.mdx | 2 +- 3 files changed, 29 insertions(+), 5 deletions(-) diff --git a/references/api/api_guides/migrating-to-requests-v3.mdx b/references/api/api_guides/migrating-to-requests-v3.mdx index 54f82725..f9d0ce68 100644 --- a/references/api/api_guides/migrating-to-requests-v3.mdx +++ b/references/api/api_guides/migrating-to-requests-v3.mdx @@ -3,12 +3,22 @@ title: "Migrating to Requests v3" description: "What changed in GET /requests/v3 and how to upgrade from v2." --- -`GET /requests/v3` is the latest version of the Requests API. It gives you a richer query surface with advanced filtering across status, chains, amounts, addresses, time, and more, plus a cleaner and more consistent response. This guide covers every change and how to upgrade. v2 stays available, so you can migrate at your own pace. +`GET /requests/v3` is the latest version of the Requests API. It gives you a richer query surface with advanced filtering across status, chains, amounts, addresses, time, and more, plus a cleaner and more consistent response. This guide covers every change and how to upgrade. `GET /requests/v2` remains available during a deprecation window (see the [sunset timeline](#sunset-timeline) below) — migrate before it's retired. `x-api-key` is now required. Every v3 request authenticates against an active API key. See [API Keys](/references/api/api-keys) for details. +## Sunset timeline + +`GET /requests/v2` is **deprecated as of July 22, 2026**. It keeps working, but migrate to `GET /requests/v3` before it's fully retired on **November 22, 2026**. + +| Date | What changes | +| --- | --- | +| **Jul 22, 2026** | v2 is deprecated; v3 is the recommended version. v2 keeps working. | +| **Aug 22, 2026 onward** | v2's rate limit is progressively reduced each month; requests over the limit receive `429`. | +| **Nov 22, 2026** | v2 is fully retired — all traffic must be on v3. | + ## Response shape The same request shown in full for v2 and v3, plus a focused diff of what moved. @@ -158,6 +168,7 @@ The same request shown in full for v2 and v3, plus a focused diff of what moved. } }, "platformFee": null, + "quoteOraclePrice": null, "referrer": "my-app|user-123", "refundCurrencyData": null, "externalMetadata": { "moonpayId": null } @@ -185,7 +196,7 @@ The same request shown in full for v2 and v3, plus a focused diff of what moved. "sender": "0xE7a205...", // [!code ++] promoted from data.metadata.sender "refundTo": null, // [!code ++] "requestType": "Bridge", // [!code ++] - "depositAddress": null, // now an object: { address, type, depositor, depositTxHash } + "depositAddress": null, // now an object: { address, type, depositor, depositTxHash, recoveryAddress } "referrer": "my-app|user-123", // [!code --] moved to data.referrer (authenticated) "features": ["app_fees"], // [!code ++] "data": { @@ -239,6 +250,10 @@ The same request shown in full for v2 and v3, plus a focused diff of what moved. + + The full OpenAPI schema lives at [api.relay.link/documentation/json](https://api.relay.link/documentation/json). + + **`data.fees` has changed meaning.** The key `fees` is reused for a different shape. In v2, `data.fees` was raw wei (`gas`/`fixed`/`price`/`gateway`). In v3 that object is removed, and `data.fees` now holds the per-component USD breakdown that v2 called `expandedPriceImpact`. Code reading `data.fees.gas` will break — read `data.fees.quoted` / `data.fees.actual` instead. @@ -360,7 +375,7 @@ Every individual change, grouped by request side and response side. - `data.route.quoted` — the route as quoted at request time. - `data.route.actual` — what actually executed. Carries `rate`, and `actual` falls back to `quoted` when there's no execution data yet (e.g. same-chain swaps). - Each phase has `origin` and `destination` sides, and each side has `inputCurrency` / `outputCurrency` (each a full amount object) plus `router`. `includedSwapSources` / `includedOriginSwapSources` / `includedDestinationSwapSources` are hoisted to the top of `data.route`. + Each phase has `origin` and `destination` sides, and each side has `inputCurrency` / `outputCurrency` (each a full amount object) plus `router` (on the `actual` route, `router` reflects the provider that actually filled the leg, not always `"relay"`). `includedSwapSources` / `includedOriginSwapSources` / `includedDestinationSwapSources` are hoisted to the top of `data.route`. There is **no `data.swap`** and **no `data.quotedOutputAmount`** — read amounts from the route instead: @@ -405,7 +420,8 @@ Every individual change, grouped by request side and response side. - **`refundTo`** (refund target for deposit-address transactions) is **added** at the root. - **`requestType`** (`Bridge`, `Crosschain Swap`, `Same-chain Swap`, `Send`, `Wrap`, `Unwrap`, `Call`) is **added** at the root. - **`features`** (e.g. `gasless_execution`, `fast_fill`, `gas_top_up`, `app_fees`, `deposit_address`) is **added** at the root. - - **`depositAddress`** is now a structured object: `{ address, type: "strict" | "open", depositor, depositTxHash }`. + - **`depositAddress`** is now a structured object: `{ address, type: "strict" | "open", depositor, depositTxHash, recoveryAddress }`. `recoveryAddress` is the origin-chain address that can recover deposit-address funds if the recipient wallet is later blocked (`null` when not set). + - **`data.quoteOraclePrice`** is **added** — the oracle price snapshot at quote time (`{ rate, observedAt, inputCurrency, outputCurrency }`), returned only for fixed-BPS oracle integrators; `null` otherwise. - `data.price` is **removed** — read the quoted output amount from `data.route.actual.destination.inputCurrency` (distinct from the actual received amount in `data.route.actual.destination.outputCurrency`). - `failReason` / `refundFailReason` use **`null`** instead of the string `"N/A"`. @@ -450,6 +466,8 @@ Every individual change, grouped by request side and response side. | `sender` (root) | promoted from `data.metadata.sender` | | `features` (root) | request feature flags (`gasless_execution`, `fast_fill`, `app_fees`, …) | | `refundTo` | refund target for deposit-address flows | + | `depositAddress.recoveryAddress` | origin-chain address that can recover deposit-address funds if the recipient is later blocked | + | `data.quoteOraclePrice` | oracle price snapshot at quote time (`rate`, `observedAt`, `inputCurrency`, `outputCurrency`); fixed-BPS oracle integrators only | | `data.route.actual` | executed route (with `rate`); falls back to `quoted` | | `data.externalMetadata` | partner correlation IDs (e.g. `moonpayId`) | | `feeSponsorship.actual.sponsorPayment` | what the sponsor actually paid | diff --git a/references/api/changelog.mdx b/references/api/changelog.mdx index 7b0f5563..a95ba1cc 100644 --- a/references/api/changelog.mdx +++ b/references/api/changelog.mdx @@ -3,6 +3,12 @@ title: "API Changelog" description: "Record of breaking changes, deprecations, and notable additions to the Relay API" --- +## 2026-07-22 — `GET /requests/v3` is live; `GET /requests/v2` deprecated & scheduled for sunset + +**Added** — `GET /requests/v3`: the recommended Requests API. It requires `x-api-key`, adds a broad filter/search/sort surface, and returns a cleaner, consolidated response. See the [migration guide](/references/api/api_guides/migrating-to-requests-v3). + +**Deprecated** — `GET /requests/v2` is deprecated as of today. It keeps working for now, but its rate limit will be progressively reduced each month until it is **fully retired on November 22, 2026**. Migrate to v3 before then — see the [sunset timeline](/references/api/api_guides/migrating-to-requests-v3#sunset-timeline). + ## 2026-07-02 — Quote protocol-data opt-in for onchain order verification **Breaking** — `POST /quote` and `POST /quote/v2`: the opt-in request flag `includeProtocolSignature` is renamed to `includeProtocolData`. The previous name is no longer honored. Integrators that were passing `includeProtocolSignature: true` to receive `protocol.v2.orderSignature` must switch to `includeProtocolData: true`. Setting this opt-in may increase quote response latency. diff --git a/references/api/get-requests-v2.mdx b/references/api/get-requests-v2.mdx index d1fe4f42..81a8224e 100644 --- a/references/api/get-requests-v2.mdx +++ b/references/api/get-requests-v2.mdx @@ -5,5 +5,5 @@ openapi: get /requests/v2 --- - `GET /requests/v2` is deprecated. New integrations should use [`GET /requests/v3`](/references/api/get-requests), which requires authentication and offers a richer filter surface and a cleaner response. See the [migration guide](/references/api/api_guides/migrating-to-requests-v3) for what changed and how to upgrade. + `GET /requests/v2` is **deprecated as of July 22, 2026** and is being sunset: its rate limit is reduced each month until it is **fully retired on November 22, 2026**. New integrations should use [`GET /requests/v3`](/references/api/get-requests), which requires authentication and offers a richer filter surface and a cleaner response. See the [migration guide](/references/api/api_guides/migrating-to-requests-v3#sunset-timeline) for the full timeline and how to upgrade. From 31e8b404b638a1f9dde0d3e01cf23296cc690d35 Mon Sep 17 00:00:00 2001 From: Ted Palmer Date: Wed, 22 Jul 2026 13:00:51 -0400 Subject: [PATCH 8/8] Update dates --- references/api/api_guides/migrating-to-requests-v3.mdx | 6 +++--- references/api/changelog.mdx | 2 +- references/api/get-requests-v2.mdx | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/references/api/api_guides/migrating-to-requests-v3.mdx b/references/api/api_guides/migrating-to-requests-v3.mdx index f9d0ce68..58f0058a 100644 --- a/references/api/api_guides/migrating-to-requests-v3.mdx +++ b/references/api/api_guides/migrating-to-requests-v3.mdx @@ -11,13 +11,13 @@ description: "What changed in GET /requests/v3 and how to upgrade from v2." ## Sunset timeline -`GET /requests/v2` is **deprecated as of July 22, 2026**. It keeps working, but migrate to `GET /requests/v3` before it's fully retired on **November 22, 2026**. +`GET /requests/v2` is **deprecated as of July 22, 2026**. It keeps working, but migrate to `GET /requests/v3` before it's fully retired on **November 24, 2026**. | Date | What changes | | --- | --- | | **Jul 22, 2026** | v2 is deprecated; v3 is the recommended version. v2 keeps working. | -| **Aug 22, 2026 onward** | v2's rate limit is progressively reduced each month; requests over the limit receive `429`. | -| **Nov 22, 2026** | v2 is fully retired — all traffic must be on v3. | +| **Sep 1, 2026 onward** | v2's rate limit is progressively reduced each month; requests over the limit receive `429`. | +| **Nov 24, 2026** | v2 is fully retired — all traffic must be on v3. | ## Response shape diff --git a/references/api/changelog.mdx b/references/api/changelog.mdx index a95ba1cc..a3bff1d3 100644 --- a/references/api/changelog.mdx +++ b/references/api/changelog.mdx @@ -7,7 +7,7 @@ description: "Record of breaking changes, deprecations, and notable additions to **Added** — `GET /requests/v3`: the recommended Requests API. It requires `x-api-key`, adds a broad filter/search/sort surface, and returns a cleaner, consolidated response. See the [migration guide](/references/api/api_guides/migrating-to-requests-v3). -**Deprecated** — `GET /requests/v2` is deprecated as of today. It keeps working for now, but its rate limit will be progressively reduced each month until it is **fully retired on November 22, 2026**. Migrate to v3 before then — see the [sunset timeline](/references/api/api_guides/migrating-to-requests-v3#sunset-timeline). +**Deprecated** — `GET /requests/v2` is deprecated as of today. It keeps working for now, but its rate limit will be progressively reduced each month until it is **fully retired on November 24, 2026**. Migrate to v3 before then — see the [sunset timeline](/references/api/api_guides/migrating-to-requests-v3#sunset-timeline). ## 2026-07-02 — Quote protocol-data opt-in for onchain order verification diff --git a/references/api/get-requests-v2.mdx b/references/api/get-requests-v2.mdx index 81a8224e..f8ea6c00 100644 --- a/references/api/get-requests-v2.mdx +++ b/references/api/get-requests-v2.mdx @@ -5,5 +5,5 @@ openapi: get /requests/v2 --- - `GET /requests/v2` is **deprecated as of July 22, 2026** and is being sunset: its rate limit is reduced each month until it is **fully retired on November 22, 2026**. New integrations should use [`GET /requests/v3`](/references/api/get-requests), which requires authentication and offers a richer filter surface and a cleaner response. See the [migration guide](/references/api/api_guides/migrating-to-requests-v3#sunset-timeline) for the full timeline and how to upgrade. + `GET /requests/v2` is **deprecated as of July 22, 2026** and is being sunset: its rate limit is reduced each month until it is **fully retired on November 24, 2026**. New integrations should use [`GET /requests/v3`](/references/api/get-requests), which requires authentication and offers a richer filter surface and a cleaner response. See the [migration guide](/references/api/api_guides/migrating-to-requests-v3#sunset-timeline) for the full timeline and how to upgrade.