@switch-win/sdk 1.2.1 → 1.2.3

package/README.md

@@ -3,11 +3,11 @@
 [![npm version](https://img.shields.io/npm/v/@switch-win/sdk.svg)](https://www.npmjs.com/package/@switch-win/sdk)
 [![npm downloads](https://img.shields.io/npm/dm/@switch-win/sdk.svg)](https://www.npmjs.com/package/@switch-win/sdk)
 
-> **Official integration kit for the Switch DEX Aggregator on PulseChain and Robinhood Chain**
+> **Official integration kit for the Switch DEX Aggregator on PulseChain and Robinhood Chain**
 
 Everything partners need to integrate Switch swaps and limit orders — API docs, TypeScript types, ABIs, constants, and ready-to-use examples.
 
-**Swap API:** `https://quote.switch.win`  |  **Swap chains:** PulseChain (369), Robinhood Chain (4663)  |  **Limit orders:** PulseChain
+**Swap API:** `https://quote.switch.win`  |  **Swap chains:** PulseChain (369), Robinhood Chain (4663)  |  **Limit orders:** PulseChain and Robinhood Chain
 
 ---
 
@@ -20,9 +20,9 @@ Switch-SDK/
 ├── src/
 │   ├── index.ts                       # Main entry — re-exports everything
 │   ├── types.ts                       # TypeScript types (swap + limit orders)
-│   ├── constants.ts                   # PulseChain addresses, ABIs, EIP-712, PLSFlow config
-│   ├── networks/
-│   │   └── robinhood.ts               # Robinhood metadata, contracts, tokens, quote URL helper
+│   ├── constants.ts                   # PulseChain addresses, ABIs, EIP-712, PLSFlow config
+│   ├── networks/
+│   │   └── robinhood.ts               # Robinhood metadata, contracts, tokens, quote URL helper
 │   └── limit-orders.ts               # Limit order helpers (build, sign, submit, query, PLSFlow)
 ├── abi/
 │   ├── SwitchRouterABI.json           # Full SwitchRouter contract ABI
@@ -42,26 +42,26 @@ Switch-SDK/
 
 0. [Installation](#installation)
 
-### Swaps
-
-1. [Quickstart](#quickstart)
-2. [Robinhood Chain](#robinhood-chain)
-3. [Authentication](#authentication)
-4. [Swap Integration Flow](#swap-integration-flow)
-5. [Swap API Reference](#swap-api-reference)
-6. [Error Handling](#error-handling)
-7. [Partner Fee Sharing](#partner-fee-sharing)
+### Swaps
+
+1. [Quickstart](#quickstart)
+2. [Robinhood Chain](#robinhood-chain)
+3. [Authentication](#authentication)
+4. [Swap Integration Flow](#swap-integration-flow)
+5. [Swap API Reference](#swap-api-reference)
+6. [Error Handling](#error-handling)
+7. [Partner Fee Sharing](#partner-fee-sharing)
 
 ### Limit Orders
 
-8. [Limit Orders](#limit-orders) — full guide in [`LIMIT-ORDERS.md`](LIMIT-ORDERS.md)
+8. [Limit Orders](#limit-orders) — full guide in [`LIMIT-ORDERS.md`](LIMIT-ORDERS.md)
 
 ### General
 
-9. [Constants & Addresses](#constants--addresses)
-10. [Full Integration Examples](#full-integration-examples)
-11. [Rate Limits](#rate-limits)
-12. [Support](#support)
+9. [Constants & Addresses](#constants--addresses)
+10. [Full Integration Examples](#full-integration-examples)
+11. [Rate Limits](#rate-limits)
+12. [Support](#support)
 
 ---
 
@@ -86,7 +86,7 @@ Get a swap quote and execute it in **three steps**:
 curl -H "x-api-key: YOUR_KEY" \
   "https://quote.switch.win/swap/quote?network=pulsechain&from=0xA1077a294dDE1B09bB078844df40758a5D0f9a27&to=0x95B303987A60C71504D99Aa1b13B4DA07b0790ab&amount=1000000000000000000&sender=0xYOUR_WALLET&slippage=100"
 
-# 2. Approve the SwitchRouter to spend your input token (ERC-20 only; skip for native currency)
+# 2. Approve the SwitchRouter to spend your input token (ERC-20 only; skip for native currency)
 
 # 3. Send the transaction using the `tx` object from the response:
 #    { to: "0x0305...", data: "0x...", value: "0" }
@@ -106,7 +106,7 @@ const res = await fetch(
 );
 const quote: BestPathResponse = await res.json();
 
-// 2. Approve SwitchRouter (ERC-20 only — skip for native currency)
+// 2. Approve SwitchRouter (ERC-20 only — skip for native currency)
 const token = new ethers.Contract(fromToken, ["function approve(address,uint256)"], signer);
 await (await token.approve(SWITCH_ROUTER, amount)).wait();
 
@@ -116,40 +116,44 @@ await signer.sendTransaction(quote.tx);
 
 > **⚠️ Always use `tx.to` from the quote response** when sending swap transactions. Do NOT hardcode the router address — the contract may be redeployed.
 
-For a production integration with tax token handling, adapter filtering, and fee mode selection, see [Swap Integration Flow](#swap-integration-flow) and the [full examples](examples/).
-
-### Robinhood Chain
-
-Robinhood uses the same quote endpoint; set `network=robinhood`. The dedicated
+For a production integration with tax token handling, adapter filtering, and fee mode selection, see [Swap Integration Flow](#swap-integration-flow) and the [full examples](examples/).
+
+### Robinhood Chain
+
+Robinhood uses the same quote endpoint; set `network=robinhood`. The dedicated
 module includes canonical chain metadata, deployed Switch contracts, vetted
 routing hubs, and a URL builder that always includes the correct network.
-
-For network configuration, deployed addresses, tax handling, execution, and
-the complete frontend token list, see [`ROBINHOOD.md`](ROBINHOOD.md).
-
-```ts
-import {
-  ROBINHOOD_NATIVE_ETH,
-  ROBINHOOD_TOKENS,
-  buildRobinhoodQuoteUrl,
-} from "@switch-win/sdk/networks/robinhood";
-
-const url = buildRobinhoodQuoteUrl({
-  from: ROBINHOOD_NATIVE_ETH,
-  to: ROBINHOOD_TOKENS.USDG.address,
-  amount: 1_000_000_000_000_000n,
-  sender: walletAddress,
-  slippage: 50,
-});
-
-const response = await fetch(url, {
-  headers: { "x-api-key": process.env.SWITCH_API_KEY! },
-});
-```
-
-Always approve `ROBINHOOD_SWITCH_CONTRACTS.router` for ERC-20 input, but submit
-the transaction to `quote.tx.to` so integrations remain safe across router
-upgrades. Limit-order helpers in this package remain PulseChain-only.
+The production router exposes fourteen adapters across Uniswap, SwapHood,
+Up33, Sheriff, Aeon, Catnip, PancakeSwap, RobinSwap, SushiSwap, and Switch limit
+orders.
+
+For network configuration, deployed addresses, tax handling, execution, and
+the complete frontend token list, see [`ROBINHOOD.md`](ROBINHOOD.md).
+
+```ts
+import {
+  ROBINHOOD_NATIVE_ETH,
+  ROBINHOOD_TOKENS,
+  buildRobinhoodQuoteUrl,
+} from "@switch-win/sdk/networks/robinhood";
+
+const url = buildRobinhoodQuoteUrl({
+  from: ROBINHOOD_NATIVE_ETH,
+  to: ROBINHOOD_TOKENS.USDG.address,
+  amount: 1_000_000_000_000_000n,
+  sender: walletAddress,
+  slippage: 100, // 1%, matching the Robinhood frontend default
+});
+
+const response = await fetch(url, {
+  headers: { "x-api-key": process.env.SWITCH_API_KEY! },
+});
+```
+
+Always approve `ROBINHOOD_SWITCH_CONTRACTS.router` for ERC-20 input, but submit
+the transaction to `quote.tx.to` so integrations remain safe across router
+upgrades. Robinhood limit-order deployment constants and EIP-712 domain values
+are exported from `src/networks/robinhood.ts`.
 
 ---
 
@@ -250,8 +254,8 @@ function determineFeeOnOutput(
   const isSellTax = fromTax.isTaxToken && fromTax.sellTaxBps > 0;
   const isBuyTax = toTax.isTaxToken && toTax.buyTaxBps > 0;
 
-  // Both tokens are taxed — use fee on input to avoid extra output transfers.
-  if (isSellTax && isBuyTax) return false;
+  // Both tokens are taxed — use fee on input to avoid extra output transfers.
+  if (isSellTax && isBuyTax) return false;
 
   // Only output token is tax — fee on input (avoids router holding output tokens)
   if (isBuyTax) return false;
@@ -290,15 +294,15 @@ Fee portion: Router ──transfer──▶ FeeClaimer (3rd buy tax on fee amoun
 ```
 The output token is transferred **three times** through different addresses, each incurring a buy tax. The user receives significantly less than expected.
 
-**Bottom line:** When the output token has a buy tax, always use `feeOnOutput=false` so the router routes output directly to the user in a single transfer. This applies to both regular swaps and limit orders.
-
-### Executing the Swap
+**Bottom line:** When the output token has a buy tax, always use `feeOnOutput=false` so the router routes output directly to the user in a single transfer. This applies to both regular swaps and limit orders.
+
+### Executing the Swap
 
 Once you have a quote, execute it in two steps:
 
 #### Step 1 — Approve Token Spend (ERC-20 inputs only)
 
-If the input token is an **ERC-20** rather than the chain's native currency, the user must approve the network's SwitchRouter contract to spend `amount` tokens before submitting the swap.
+If the input token is an **ERC-20** rather than the chain's native currency, the user must approve the network's SwitchRouter contract to spend `amount` tokens before submitting the swap.
 
 Before sending an approval transaction, check whether the user already has sufficient allowance to avoid wasting gas on a redundant approve:
 
@@ -326,7 +330,7 @@ const { tx } = quoteResponse;
 const txResponse = await signer.sendTransaction({
   to:    tx.to,
   data:  tx.data,
-  value: tx.value,   // "0" for ERC-20 inputs, amountIn for native currency
+  value: tx.value,   // "0" for ERC-20 inputs, amountIn for native currency
 });
 
 const receipt = await txResponse.wait();
@@ -386,7 +390,7 @@ Returns all available DEX adapters with their on-chain indices and contract addr
 
 | Param | Required | Type | Description |
 |---|---|---|---|
-| `network` | **Yes** | string | Target blockchain network: `"pulsechain"` or `"robinhood"`. |
+| `network` | **Yes** | string | Target blockchain network: `"pulsechain"` or `"robinhood"`. |
 
 #### Authentication
 
@@ -455,7 +459,7 @@ Detects whether a token has a fee-on-transfer mechanism (tax token) and returns
 | Parameter | Required | Type | Description |
 |---|---|---|---|
 | `token` | **Yes** | address | Token address to check (0x + 40 hex chars) |
-| `network` | No | string | Target blockchain: `"pulsechain"` or `"robinhood"`. |
+| `network` | No | string | Target blockchain: `"pulsechain"` or `"robinhood"`. |
 
 #### Latency
 
@@ -569,9 +573,9 @@ Returns the optimal split-route for a swap and (optionally) a ready-to-send tran
 
 | Parameter | Required | Type | Default | Description |
 |---|---|---|---|---|
-| `network` | **Yes** | string | — | Target blockchain network: `"pulsechain"` or `"robinhood"`. |
-| `from` | **Yes** | address | — | Input token address. Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` for the network's native currency (PLS or ETH). |
-| `to` | **Yes** | address | — | Output token address. Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` for the network's native currency (PLS or ETH). |
+| `network` | **Yes** | string | — | Target blockchain network: `"pulsechain"` or `"robinhood"`. |
+| `from` | **Yes** | address | — | Input token address. Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` for the network's native currency (PLS or ETH). |
+| `to` | **Yes** | address | — | Output token address. Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` for the network's native currency (PLS or ETH). |
 | `amount` | **Yes** | string | — | Input amount in **wei** (raw integer string, no decimals). Max: 10²⁷. |
 | `sender` | No* | address | — | Sender wallet address. **Required to receive `tx` calldata in the response.** |
 | `receiver` | No | address | `sender` | Custom recipient address. If omitted, output tokens are sent to `sender`. |
@@ -660,7 +664,7 @@ GET /swap/quote?network=pulsechain&from=0xA1077a294dDE1B09bB078844df40758a5D0f9a
   "tx": {
     "to": "0x0305fcb5dA680EA6fd1B01A96C1949175B99d406",
     "data": "0x...",     // ABI-encoded goSwitch() calldata with feeOnOutput = false
-    "value": "0"          // "0" for ERC-20 input; amountIn for native-currency input
+    "value": "0"          // "0" for ERC-20 input; amountIn for native-currency input
   },
   // Same swap but with fee taken from the output token instead
   "txFeeOnOutput": {
@@ -798,7 +802,7 @@ Errors are returned as JSON with an `error` field:
 | Error | Cause |
 |---|---|
 | `"Missing required parameter: network"` | `network` query param absent |
-| `"This network is not supported at this time."` | `network` is not a supported value (`"pulsechain"` or `"robinhood"`) |
+| `"This network is not supported at this time."` | `network` is not a supported value (`"pulsechain"` or `"robinhood"`) |
 | `"Missing required parameters: from, to, amount"` | One or more required query params absent |
 | `"Invalid from address (must be 0x + 40 hex chars)"` | `from` is not a valid hex address |
 | `"Invalid to address (must be 0x + 40 hex chars)"` | `to` is not a valid hex address |
@@ -828,7 +832,7 @@ If the swap transaction reverts on-chain, the SwitchRouter contract returns one
 | `FinalAmountOutTooLow()` | Output after fees fell below `_minTotalAmountOut` — price moved beyond your slippage tolerance. Retry with a fresh quote or increase slippage. |
 | `ExcessiveFee()` | `_fee` exceeds the contract maximum (100 bps / 1 %). |
 | `InsufficientFee()` | `_fee` is below the protocol's `MIN_FEE`. Contact the Switch team if you need a lower fee. |
-| `MsgValueMismatch()` | For native-currency swaps, `msg.value` must exactly equal the route's total `amountIn`. |
+| `MsgValueMismatch()` | For native-currency swaps, `msg.value` must exactly equal the route's total `amountIn`. |
 | `ZeroInput()` | No input amount was provided. |
 
 ---
@@ -881,11 +885,11 @@ function shouldFeeOnOutput(from: string, to: string, quote?: BestPathResponse):
   if (toAddr === MY_PROJECT_TOKEN)   return false;  // fee on input  = collect input
 
   // Priority 2: Avoid collecting tax tokens (fee revenue lost to transfer tax)
-  if (quote) {
-    const fromIsTax = quote.fromTokenTax?.isTaxToken ?? false;
-    const toIsTax   = quote.toTokenTax?.isTaxToken ?? false;
-    if (fromIsTax && toIsTax) return false;
-    if (fromIsTax && !toIsTax) return true;   // collect non-tax output
+  if (quote) {
+    const fromIsTax = quote.fromTokenTax?.isTaxToken ?? false;
+    const toIsTax   = quote.toTokenTax?.isTaxToken ?? false;
+    if (fromIsTax && toIsTax) return false;
+    if (fromIsTax && !toIsTax) return true;   // collect non-tax output
     if (toIsTax && !fromIsTax) return false;  // collect non-tax input
   }
 
@@ -916,26 +920,30 @@ await signer.sendTransaction(chosenTx);
 
 ## Limit Orders
 
-Switch Limit Orders let users place **gasless, signed orders** that are filled automatically when market conditions are met — no gas to create, no token deposits, EIP-712 signed.
-
-**→ Full integration guide: [`LIMIT-ORDERS.md`](LIMIT-ORDERS.md)**
-
-Covers: creating orders, approvals, `feeOnOutput` decision guide (tax tokens & operator flexibility), querying, cancellation, API reference, types, and EIP-712 details.
+Switch Limit Orders let users place **gasless, signed orders** that are filled automatically when market conditions are met — no gas to create, no token deposits, EIP-712 signed.
+
+**→ Full integration guide: [`LIMIT-ORDERS.md`](LIMIT-ORDERS.md)**
+
+Covers both `pulsechain` and `robinhood`: creating orders, live deployment
+discovery, approvals, `feeOnOutput` decision rules, native PLS/ETH flows,
+querying, cancellation, API types, and EIP-712 details. Use
+`fetchLimitOrderConfig({ network })` at startup and include `network` in every
+orderbook request.
 
 ---
 
 ## Constants & Addresses
 
-PulseChain constants are importable from [`src/constants.ts`](src/constants.ts).
-Robinhood constants are available from
-[`src/networks/robinhood.ts`](src/networks/robinhood.ts); see the complete
-[`ROBINHOOD.md`](ROBINHOOD.md) integration reference.
+PulseChain constants are importable from [`src/constants.ts`](src/constants.ts).
+Robinhood constants are available from
+[`src/networks/robinhood.ts`](src/networks/robinhood.ts); see the complete
+[`ROBINHOOD.md`](ROBINHOOD.md) integration reference.
 
 > **⚠️ Do not hardcode the SwitchRouter address.** The router contract may be redeployed from time to time. Always use the `tx.to` (or `txFeeOnOutput.to`) address returned by the `/bestPath` API response when building your transaction. This ensures your integration automatically picks up router upgrades without code changes.
 
 | Name | Value |
 |---|---|
-| **Chain** | PulseChain (Chain ID `369`); Robinhood Chain uses ID `4663` and network-specific exports |
+| **Chain** | PulseChain (Chain ID `369`); Robinhood Chain uses ID `4663` and network-specific exports |
 | **SwitchRouter** | `0x0305fcb5dA680EA6fd1B01A96C1949175B99d406` |
 | **SwitchLimitOrder** (V2 — current) | `0x8e3881bdF81Fc0211383B2e576076B654F7aFD86` |
 | **SwitchLimitOrder** (V1 — legacy) | `0x0e884072a891b406C0D814907A1E2310fE5F5Deb` |