docs(bridge-api): NEAR Intents routing provider + supported matrix endpoint

integration/api-doc/api-for-advanced-used/get-fees.md

@@ -47,3 +47,52 @@ curl --location --request POST 'https://intentapiv4.rozo.ai/functions/v1/payment
 ```
 
 > **Note**: The `dryrun=true` parameter returns fee details without creating a payment record.
+
+## Which rail charged the fee
+
+Dry-run and create responses also carry a `feeInfo` block that names the routing provider the fee belongs to, so you always know whether a quote is priced on Rozo's own rails or on NEAR Intents:
+
+```json
+"provider": "near",
+"feeInfo": {
+  "feePercentage": "0.3%",
+  "minimumFee": "$0.01",
+  "provider": "near",
+  "feeTier": "near-routing"
+}
+```
+
+| Provider | Rate |
+| --- | --- |
+| `rozo` | your app tier (public default 0.1%, minimum $0.01) |
+| `near` | flat 0.3% (minimum $0.01); per-destination minimums still apply (e.g. Solana $0.20, Ethereum $0.10, USDT on Tron $1) |
+
+`feePercentage` is the **effective** rate: when a minimum fee applies to a small order it shows the real percentage, not the nominal one.
+
+## Rate card without a dry run
+
+`GET /payment-api/payments/supported` returns the schedule-level rate card for both rails together with the supported chain/token matrix:
+
+```bash
+curl 'https://intentapiv4.rozo.ai/functions/v1/payment-api/payments/supported'
+```
+
+```json
+{
+  "fees": {
+    "rozo": { "feePercentage": "0.1%", "minimumFee": "$0.01" },
+    "near": { "feePercentage": "0.3%", "minimumFee": "$0.01", "feeTier": "near-routing" }
+  },
+  "data": [ ... ]
+}
+```
+
+These numbers are indicative. The binding fee for a specific order is always the dry-run `feeInfo`.
+
+## Errors specific to NEAR-routed quotes
+
+| Error code | Meaning |
+| --- | --- |
+| `ROUTE_NOT_SUPPORTED_BY_PROVIDER` | You asked for `provider: "near"` on a route it cannot serve. |
+| `AMOUNT_TOO_SMALL` | Below the route's minimum; the response includes `minimumSourceAmount`. |
+| `NEGATIVE_ROUTE_ECONOMICS` | The amount is too small to cover the network cost of this route; send a larger amount. |

integration/api-doc/api-quick-start.md

@@ -86,4 +86,41 @@ curl --location --request POST 'https://intentapiv4.rozo.ai/functions/v1/payment
 }
 ```
 
-  
+### Routing provider (optional)
+
+Every payment is executed on one of two rails. You can leave the choice to Rozo or ask for a rail by name with the optional `provider` field:
+
+```json
+{
+  "appId": "rozodevDemo",
+  "type": "exactIn",
+  "provider": "auto",
+  "source": { "chainId": "10", "tokenSymbol": "USDC", "amount": "20.00" },
+  "destination": { "chainId": "8453", "tokenSymbol": "USDC", "receiverAddress": "0x..." }
+}
+```
+
+| `provider` | Meaning | Fee |
+| --- | --- | --- |
+| `auto` (default) | Rozo picks: our own rails for every route we serve, NEAR Intents only for routes we cannot serve (e.g. an Optimism source). | whichever rail is chosen |
+| `rozo` | Rozo's own rails. | your app tier (public default 0.1%) |
+| `near` | Routed through [NEAR Intents](https://near-intents.org). | flat 0.3% |
+
+Notes:
+
+* Omitting `provider` behaves exactly as before — existing integrations need no change.
+* The response always echoes the **resolved** rail in `provider` (never `auto`) and in `feeInfo.provider`, so you can show users which rail and fee applied (e.g. "0.1% via Rozo" / "0.3% via NEAR Intents").
+* `near` orders can currently settle only on Base (`8453`), Solana (`900`) and Stellar (`1500`). Asking for `near` on a route it cannot serve returns `400 ROUTE_NOT_SUPPORTED_BY_PROVIDER` — it is never silently downgraded.
+* `near` deposit addresses are single-use and expire; never reuse one.
+* Use [`GET /payment-api/payments/supported`](supported-tokens-and-chains.md#live-supported-matrix) to discover which rails serve which chains and tokens.
+
+Every create and dry-run response includes a `feeInfo` block:
+
+```json
+"feeInfo": {
+  "feePercentage": "0.3%",
+  "minimumFee": "$0.01",
+  "provider": "near",
+  "feeTier": "near-routing"
+}
+```

integration/api-doc/supported-tokens-and-chains.md

@@ -1,5 +1,36 @@
 # Supported Tokens and Chains
 
+### Live supported matrix
+
+The tables on this page are a snapshot. The always-current, machine-readable list is served by the API itself — use it to populate chain/token pickers instead of hardcoding:
+
+```bash
+curl 'https://intentapiv4.rozo.ai/functions/v1/payment-api/payments/supported'
+# optional filter: ?provider=rozo | ?provider=near
+```
+
+Each entry describes one (chain, token) leg in Rozo's own naming:
+
+```json
+{
+  "chainId": "10",
+  "chainName": "Optimism",
+  "chainAliases": ["op", "optimism"],
+  "addressFormat": "evm",
+  "tokenSymbol": "USDC",
+  "providers": ["near"],
+  "destinationProviders": [],
+  "destinationMinimumFee": "$0.10"
+}
+```
+
+* `providers` — rails that accept this leg as a **pay-in source**.
+* `destinationProviders` — rails that can **pay out to** it. They differ for `near`: it accepts pay-ins from many chains but only settles on Base, Solana and Stellar.
+* `destinationMinimumFee` — present only when a per-destination minimum fee applies.
+* The top-level `fees` object is the rate card per rail (see [Get Fees](api-for-advanced-used/get-fees.md)).
+
+New chains and tokens appear here automatically as they are enabled — for example Optimism USDC/USDT is currently available as a pay-in source via the `near` rail. See [Routing provider](api-quick-start.md#routing-provider-optional) for how to select a rail.
+
 > **Note on Chain IDs for Solana and Stellar:** For non-EVM chains, the API accepts **either** the numeric chain ID **or** the lowercase chain name string:
 > - **Solana** — `900` or `"solana"`
 > - **Stellar** — `1500` or `"stellar"`