@switch-win/sdk 1.1.0 → 1.2.1

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**
+> **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`  |  **Limit Order API:** `https://quote.switch.win`  |  **Chain:** PulseChain (369)
+**Swap API:** `https://quote.switch.win`  |  **Swap chains:** PulseChain (369), Robinhood Chain (4663)  |  **Limit orders:** PulseChain
 
 ---
 
@@ -20,7 +20,9 @@ Switch-SDK/
 ├── src/
 │   ├── index.ts                       # Main entry — re-exports everything
 │   ├── types.ts                       # TypeScript types (swap + limit orders)
-│   ├── constants.ts                   # Addresses, ABIs, EIP-712, PLSFlow config
+│   ├── 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
@@ -40,25 +42,26 @@ Switch-SDK/
 
 0. [Installation](#installation)
 
-### Swaps
-
-1. [Quickstart](#quickstart)
-2. [Authentication](#authentication)
-3. [Swap Integration Flow](#swap-integration-flow)
-4. [Swap API Reference](#swap-api-reference)
-5. [Error Handling](#error-handling)
-6. [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
 
-7. [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
 
-8. [Constants & Addresses](#constants--addresses)
-9. [Full Integration Examples](#full-integration-examples)
-10. [Rate Limits](#rate-limits)
-11. [Support](#support)
+9. [Constants & Addresses](#constants--addresses)
+10. [Full Integration Examples](#full-integration-examples)
+11. [Rate Limits](#rate-limits)
+12. [Support](#support)
 
 ---
 
@@ -83,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 PLS)
+# 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" }
@@ -103,7 +106,7 @@ const res = await fetch(
 );
 const quote: BestPathResponse = await res.json();
 
-// 2. Approve SwitchRouter (ERC-20 only — skip for native PLS)
+// 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();
 
@@ -113,7 +116,40 @@ 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/).
+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.
 
 ---
 
@@ -214,9 +250,8 @@ function determineFeeOnOutput(
   const isSellTax = fromTax.isTaxToken && fromTax.sellTaxBps > 0;
   const isBuyTax = toTax.isTaxToken && toTax.buyTaxBps > 0;
 
-  // Both tokens are tax tokens — ALWAYS fee on input.
-  // See "Why fee-on-input for tax tokens?" below for a detailed explanation.
-  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;
@@ -255,15 +290,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** (not native PLS), the user must approve the 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:
 
@@ -291,7 +326,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 PLS
+  value: tx.value,   // "0" for ERC-20 inputs, amountIn for native currency
 });
 
 const receipt = await txResponse.wait();
@@ -351,7 +386,7 @@ Returns all available DEX adapters with their on-chain indices and contract addr
 
 | Param | Required | Type | Description |
 |---|---|---|---|
-| `network` | **Yes** | string | Target blockchain network. Currently only `"pulsechain"` is supported. |
+| `network` | **Yes** | string | Target blockchain network: `"pulsechain"` or `"robinhood"`. |
 
 #### Authentication
 
@@ -420,7 +455,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. Currently only `"pulsechain"`. |
+| `network` | No | string | Target blockchain: `"pulsechain"` or `"robinhood"`. |
 
 #### Latency
 
@@ -534,9 +569,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. Currently only `"pulsechain"` is supported. |
-| `from` | **Yes** | address | — | Input token address. Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` for native PLS. |
-| `to` | **Yes** | address | — | Output token address. Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` for native PLS. |
+| `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`. |
@@ -625,7 +660,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 PLS 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": {
@@ -763,7 +798,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 `"pulsechain"` |
+| `"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 |
@@ -793,7 +828,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 PLS 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. |
 
 ---
@@ -846,10 +881,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 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
   }
 
@@ -890,13 +926,16 @@ Covers: creating orders, approvals, `feeOnOutput` decision guide (tax tokens & o
 
 ## Constants & Addresses
 
-All constants are importable from [`src/constants.ts`](src/constants.ts).
+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`) |
+| **Chain** | PulseChain (Chain ID `369`); Robinhood Chain uses ID `4663` and network-specific exports |
 | **SwitchRouter** | `0x0305fcb5dA680EA6fd1B01A96C1949175B99d406` |
 | **SwitchLimitOrder** (V2 — current) | `0x8e3881bdF81Fc0211383B2e576076B654F7aFD86` |
 | **SwitchLimitOrder** (V1 — legacy) | `0x0e884072a891b406C0D814907A1E2310fE5F5Deb` |

package/ROBINHOOD.md

@@ -0,0 +1,610 @@
+# Switch SDK — Robinhood Chain
+
+Production integration reference for Switch swaps on Robinhood Chain mainnet.
+
+| Setting | Value |
+|---|---|
+| API network | `robinhood` |
+| Chain ID | `4663` |
+| Native currency | ETH (18 decimals) |
+| Public RPC | `https://rpc.mainnet.chain.robinhood.com` |
+| Explorer | `https://robinhoodchain.blockscout.com` |
+| Quote API | `https://quote.switch.win/swap/quote` |
+| Tax API | `https://quote.switch.win/swap/checkTax` |
+| Supported liquidity | Uniswap V2, V3, and hookless static-fee V4 |
+| Limit orders | Not currently available |
+
+## Contents
+
+- [Installation](#installation)
+- [Authentication](#authentication)
+- [Network configuration](#network-configuration)
+- [Contracts and native currency](#contracts-and-native-currency)
+- [Uniswap V4 routing](#uniswap-v4-routing)
+- [Swap integration flow](#swap-integration-flow)
+- [Quickstart](#quickstart)
+- [Tax-token checks](#tax-token-checks)
+- [Selecting `feeOnOutput`](#selecting-feeonoutput)
+- [Approving and executing](#approving-and-executing)
+- [Swap API reference](#swap-api-reference)
+- [Error handling](#error-handling)
+- [Partner fee sharing](#partner-fee-sharing)
+- [Tokens and routing](#tokens-and-routing)
+- [Rate limits](#rate-limits)
+- [Current limitations](#current-limitations)
+
+## Installation
+
+```bash
+npm install @switch-win/sdk
+```
+
+```ts
+import {
+  ROBINHOOD_CHAIN,
+  ROBINHOOD_NATIVE_ETH,
+  ROBINHOOD_SWITCH_CONTRACTS,
+  ROBINHOOD_UNISWAP_CONTRACTS,
+  ROBINHOOD_TOKENS,
+  ROBINHOOD_FEE_TOKEN_PRIORITY,
+  ROBINHOOD_FRONTEND_DEFAULT_TOKENS,
+  ROBINHOOD_FRONTEND_TOKEN_LIST,
+  buildRobinhoodQuoteUrl,
+  type BestPathResponse,
+} from "@switch-win/sdk";
+```
+
+The same exports are available from the smaller network entrypoint:
+
+```ts
+import {
+  ROBINHOOD_CHAIN,
+  ROBINHOOD_TOKENS,
+  buildRobinhoodQuoteUrl,
+} from "@switch-win/sdk/networks/robinhood";
+```
+
+## Authentication
+
+Every request to `quote.switch.win` requires a Switch API key in the
+`x-api-key` header:
+
+```ts
+const headers = {
+  "x-api-key": process.env.SWITCH_API_KEY!,
+};
+```
+
+Do not expose a production API key in browser JavaScript. Browser applications
+should call a same-origin server route that attaches the key before forwarding
+the request to Switch.
+
+## Network configuration
+
+`ROBINHOOD_CHAIN` can be adapted directly for most wallet libraries:
+
+```ts
+const robinhoodWalletChain = {
+  chainId: `0x${ROBINHOOD_CHAIN.id.toString(16)}`,
+  chainName: ROBINHOOD_CHAIN.name,
+  nativeCurrency: ROBINHOOD_CHAIN.nativeCurrency,
+  rpcUrls: [...ROBINHOOD_CHAIN.rpcUrls],
+  blockExplorerUrls: [ROBINHOOD_CHAIN.blockExplorerUrl],
+};
+
+await window.ethereum.request({
+  method: "wallet_addEthereumChain",
+  params: [robinhoodWalletChain],
+});
+```
+
+## Contracts and native currency
+
+### Switch deployment
+
+| Contract | Address |
+|---|---|
+| SwitchRouter | `0x8730C3e2cF2c8CDa8E6166837A1Ed26f46aa9E59` |
+| Uniswap V2 adapter | `0x7a14d7A8509a66209D4332843b983b29bF5604A4` |
+| Uniswap V3 adapter | `0xbcA08f296d9Ba0dc19Aa0E05D355365cE29A3205` |
+| Uniswap V4 adapter | `0x754dDCD05aFbAd1cc7Bc42B9268EB586F579E7F6` |
+
+The V4 adapter was created in
+[deployment transaction `0x60d5...34a7`](https://robinhoodchain.blockscout.com/tx/0x60d56466a8162a643a15ecde98322ec05ea23d44d03fbd817df4ddbaef4834a7)
+and added to the router in
+[activation transaction `0x405b...1098`](https://robinhoodchain.blockscout.com/tx/0x405b49619ebfe4d1a73eb2d4601d8d1e63ae3d6fff0cd811a96c17e146971098).
+
+The router constant is the ERC-20 approval target. Always submit the swap to
+`quote.tx.to`; do not replace the API-provided transaction target with a
+hardcoded address.
+
+### Native ETH and WETH
+
+Use `ROBINHOOD_NATIVE_ETH` when the user is selling or buying native ETH:
+
+```text
+0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
+```
+
+Use `ROBINHOOD_TOKENS.WETH.address` for the wrapped ERC-20:
+
+```text
+0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73
+```
+
+Native ETH does not require approval. WETH and every other ERC-20 input token
+must be approved for `ROBINHOOD_SWITCH_CONTRACTS.router`.
+
+## Uniswap V4 routing
+
+Switch's Robinhood V4 integration is designed for canonical Uniswap V4, whose
+pools share one `PoolManager`. A V4 pool is identified by its complete
+`PoolKey`:
+
+```ts
+type PoolKey = {
+  currency0: string;
+  currency1: string;
+  fee: number;
+  tickSpacing: number;
+  hooks: string;
+};
+```
+
+Do not treat V4 pools as V3 pools with another fee-tier list. The `fee`,
+`tickSpacing`, and `hooks` values are all part of pool identity, and Robinhood
+V4 discovery must preserve the full key. The backend selects the key and
+embeds adapter-specific route data in the quote; clients should submit the
+returned transaction unchanged rather than reconstructing V4 calldata.
+
+Phase one supports **hookless static-fee pools only** (`hooks` is the zero
+address, hook data is empty, and the dynamic-fee flag is not set). Pools with
+custom hooks or dynamic fees are not considered until their behavior and
+required hook data have been explicitly reviewed and allowed. This restriction
+does not reduce V2 or V3 routing coverage.
+
+V4 can represent native ETH as the zero-address currency. Switch routes use
+the canonical Robinhood WETH address, so the V4 adapter unwraps WETH when a
+selected pool consumes native ETH and wraps native ETH when that pool produces
+it. API callers should continue using `ROBINHOOD_NATIVE_ETH` for a native user
+input/output and `ROBINHOOD_TOKENS.WETH.address` for the ERC-20.
+
+The Robinhood Uniswap V4 adapter is deployed at
+`0x754dDCD05aFbAd1cc7Bc42B9268EB586F579E7F6`, whitelisted in the production
+SwitchRouter at adapter index `2`, and exported as
+`ROBINHOOD_SWITCH_CONTRACTS.uniswapV4Adapter`. Continue treating
+`GET /swap/adapters?network=robinhood` as the source of truth for the adapters
+currently available from the quote backend.
+
+The canonical Robinhood V4 infrastructure is available through
+`ROBINHOOD_UNISWAP_CONTRACTS`:
+
+| Contract | Address |
+|---|---|
+| PoolManager | `0x8366a39cc670b4001a1121b8f6a443a643e40951` |
+| PositionDescriptor | `0x9639443158e8c5efa35bd45287bf2effd3d8dc06` |
+| PositionManager | `0x58daec3116aae6d93017baaea7749052e8a04fa7` |
+| Quoter | `0x8dc178efb8111bb0973dd9d722ebeff267c98f94` |
+| StateView | `0xf3334192d15450cdd385c8b70e03f9a6bd9e673b` |
+| Universal Router | `0x8876789976decbfcbbbe364623c63652db8c0904` |
+| Permit2 | `0x000000000022D473030F116dDEE9F6B43aC78BA3` |
+
+Tax-token safety is unchanged: if either side is detected as a transfer-tax
+token, the complete route is restricted to Uniswap V2 adapter index `0`.
+Uniswap V3 and V4 are both excluded from that quote.
+
+## Swap integration flow
+
+Use the same sequence as a PulseChain integration:
+
+1. Check both tokens with `/swap/checkTax`.
+2. Select `feeOnOutput` from the tax results and preferred fee-token order.
+3. Request `/swap/quote` with `network=robinhood`, the selected fee mode, and
+   `sender` when executable calldata is required.
+4. Approve the API-provided router target for ERC-20 input tokens.
+5. Submit `quote.tx` for fee-on-input or `quote.txFeeOnOutput` for
+   fee-on-output.
+6. Show `expectedOutputAmount`, `minAmountOut`, route allocation, and detected
+   taxes to the user.
+
+Any swap involving a tax token is routed entirely through Uniswap V2. This
+also applies when both input and output are tax tokens.
+
+## Quickstart
+
+`amount` is always a raw integer amount in the input token's smallest unit.
+The following requests a quote for `0.001 ETH -> USDG`:
+
+```ts
+// This simple pair uses fee-on-input. See "Selecting feeOnOutput" below for
+// the recommended dynamic selection when community or tax tokens are involved.
+const feeOnOutput = false;
+
+const url = buildRobinhoodQuoteUrl({
+  from: ROBINHOOD_NATIVE_ETH,
+  to: ROBINHOOD_TOKENS.USDG.address,
+  amount: 1_000_000_000_000_000n,
+  sender: walletAddress,
+  slippage: 50, // 0.50%, expressed in basis points
+  feeOnOutput,
+});
+
+const response = await fetch(url, {
+  headers: { "x-api-key": process.env.SWITCH_API_KEY! },
+});
+
+if (!response.ok) {
+  throw new Error(`Switch quote failed: ${response.status}`);
+}
+
+const quote = (await response.json()) as BestPathResponse;
+const transaction = feeOnOutput ? quote.txFeeOnOutput : quote.tx;
+
+if (!transaction) {
+  throw new Error("Quote did not include the selected transaction variant");
+}
+```
+
+Equivalent curl request:
+
+```bash
+curl -H "x-api-key: YOUR_KEY" \
+  "https://quote.switch.win/swap/quote?network=robinhood&from=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&to=0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168&amount=1000000000000000&sender=0xYOUR_WALLET&slippage=50"
+```
+
+Omit `sender` for a display-only quote. Fetch again with the sender immediately
+before execution to receive current transaction calldata.
+
+## Tax-token checks
+
+Robinhood tokens can apply pair-specific transfer taxes. Check both input and
+output tokens before requesting or executing a swap:
+
+```ts
+async function checkTax(token: string) {
+  const query = new URLSearchParams({ network: "robinhood", token });
+  const response = await fetch(
+    `https://quote.switch.win/swap/checkTax?${query}`,
+    { headers: { "x-api-key": process.env.SWITCH_API_KEY! } },
+  );
+
+  if (!response.ok) throw new Error(`Tax check failed: ${response.status}`);
+  return response.json();
+}
+
+const [inputTax, outputTax] = await Promise.all([
+  checkTax(tokenIn),
+  checkTax(tokenOut),
+]);
+```
+
+The quote response also includes `fromTokenTax`, `toTokenTax`,
+`expectedOutputAmount`, and effective-slippage fields. Display these values to
+the user rather than estimating taxes locally.
+
+## Selecting `feeOnOutput`
+
+`feeOnOutput` determines which side of the swap pays the Switch partner or
+protocol fee:
+
+| Value | Fee token | Transaction field |
+|---|---|---|
+| `false` | Input token | `quote.tx` |
+| `true` | Output token | `quote.txFeeOnOutput` |
+
+Choose the mode before requesting the executable quote and pass it to
+`buildRobinhoodQuoteUrl`. This keeps `expectedOutputAmount`, routing, and the
+transaction calldata aligned with the mode that will actually be submitted.
+
+For Robinhood Chain, the recommended selection order is:
+
+1. If both sides are tax tokens, use fee-on-input (`false`) to avoid the extra
+   output-token transfers required by fee-on-output.
+2. If only the output token has buy tax, use fee-on-input (`false`) to avoid
+   routing the taxed output through additional transfers.
+3. If only the input token has sell tax, use fee-on-output (`true`) so the fee
+   is collected in the non-tax output token.
+4. Otherwise, prefer collecting tokens in this order: WETH (with native ETH
+   treated equivalently), USDG, WALLET, SEEDCOIN, then CASHCAT.
+5. If neither token is preferred, default to fee-on-input (`false`).
+
+The no-tax priority list is:
+
+| Priority | Token | Address |
+|---:|---|---|
+| 1 | WETH / native ETH | `0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73` / native sentinel |
+| 2 | USDG | `0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168` |
+| 3 | WALLET | `0x0339f5459FC690aC85F1782e15782A151b4A9E1b` |
+| 4 | SEEDCOIN | `0xD8d1C08A8bA4fc64BAC744f74290B89ADcb6Bf25` |
+| 5 | CASHCAT | `0x020bfC650A365f8BB26819deAAbF3E21291018b4` |
+
+The ordered ERC-20 addresses are exported as
+`ROBINHOOD_FEE_TOKEN_PRIORITY`. When neither side is taxed, the selector takes
+the fee from whichever side contains the higher-priority token. If neither
+side is listed, it defaults to fee-on-input.
+
+```ts
+import {
+  buildRobinhoodQuoteUrl,
+  selectRobinhoodFeeOnOutput,
+  type BestPathResponse,
+} from "@switch-win/sdk";
+
+const feeOnOutput = selectRobinhoodFeeOnOutput(
+  tokenIn,
+  tokenOut,
+  inputTax,
+  outputTax,
+);
+
+const quoteUrl = buildRobinhoodQuoteUrl({
+  from: tokenIn,
+  to: tokenOut,
+  amount: amountIn,
+  sender: walletAddress,
+  slippage: 50,
+  feeOnOutput,
+});
+
+const quoteResponse = await fetch(quoteUrl, {
+  headers: { "x-api-key": process.env.SWITCH_API_KEY! },
+});
+if (!quoteResponse.ok) {
+  throw new Error(`Switch quote failed: ${quoteResponse.status}`);
+}
+
+const quote = (await quoteResponse.json()) as BestPathResponse;
+const transaction = feeOnOutput ? quote.txFeeOnOutput : quote.tx;
+if (!transaction) {
+  throw new Error("Quote did not include the selected transaction variant");
+}
+```
+
+Do not request one fee mode and submit the other transaction variant. Taxed
+output tokens are especially important: `feeOnOutput=true` makes the router
+receive and redistribute the output, which can trigger additional transfer-tax
+events.
+
+## Approving and executing
+
+For ERC-20 input:
+
+```ts
+const token = new ethers.Contract(
+  tokenIn,
+  ["function approve(address spender, uint256 amount) returns (bool)"],
+  signer,
+);
+
+await (
+  await token.approve(ROBINHOOD_SWITCH_CONTRACTS.router, amountIn)
+).wait();
+```
+
+Then submit the transaction returned by the API:
+
+```ts
+await signer.sendTransaction({
+  to: transaction.to,
+  data: transaction.data,
+  value: transaction.value,
+});
+```
+
+For native ETH input, skip approval and send the API-provided `value`.
+
+## Swap API reference
+
+All amounts are raw integer strings in the token's smallest unit. All token and
+wallet values are EVM addresses.
+
+### List adapters
+
+```http
+GET https://quote.switch.win/swap/adapters?network=robinhood
+x-api-key: YOUR_KEY
+```
+
+Robinhood currently returns:
+
+| Index | Adapter |
+|---:|---|
+| `0` | Uniswap V2 |
+| `1` | Uniswap V3 |
+| `2` | Uniswap V4 |
+
+Treat the endpoint response, not this document, as the source of truth for
+which adapters are currently selectable.
+
+Do not permanently hard-code the available adapter list in an integration.
+Fetch it when presenting routing-source controls. If a quote involves a tax
+token, the backend overrides routing to tax-safe adapter `0`; an explicit
+filter that excludes adapter `0` is rejected.
+
+### Check token tax
+
+```http
+GET https://quote.switch.win/swap/checkTax?network=robinhood&token=0xTOKEN
+```
+
+Example response:
+
+```json
+{
+  "token": "0x...",
+  "isTaxToken": true,
+  "buyTaxBps": 500,
+  "sellTaxBps": 300
+}
+```
+
+`500` basis points is `5%`. Use the input token's `sellTaxBps` and the output
+token's `buyTaxBps`. When both tokens are taxed, use fee-on-input.
+
+### Get swap quote
+
+```http
+GET https://quote.switch.win/swap/quote
+```
+
+| Query parameter | Required | Description |
+|---|:---:|---|
+| `network` | Yes | Must be `robinhood`. |
+| `from` | Yes | Input token address or `ROBINHOOD_NATIVE_ETH`. |
+| `to` | Yes | Output token address or `ROBINHOOD_NATIVE_ETH`. |
+| `amount` | Yes | Raw input amount. |
+| `sender` | No | Required when transaction calldata is needed. |
+| `receiver` | No | Output recipient; defaults to `sender`. |
+| `slippage` | No | Basis points; default `50` (`0.5%`). |
+| `fee` | No | Partner/protocol fee in basis points. |
+| `partnerAddress` | No | Fee-sharing recipient. |
+| `feeOnOutput` | No | `true` takes the fee from output; `false` takes it from input. |
+| `adapters` | No | Comma-separated indices returned by `/swap/adapters`, such as `0,1,2`. |
+| `gasPrice` | No | Quote gas price in wei. |
+
+Omitting `sender` produces a display-only quote. Request a fresh executable
+quote with `sender` immediately before execution.
+
+### Quote response
+
+Important response fields:
+
+| Field | Description |
+|---|---|
+| `fromToken`, `toToken` | Normalized pair addresses. |
+| `totalAmountIn` | Gross input amount. |
+| `totalAmountOut` | Raw pool output before taxes and Switch fees. |
+| `expectedOutputAmount` | Expected user receipt after tax and fee, before slippage. |
+| `minAmountOut` | Minimum output encoded into calldata. |
+| `paths` | Human-readable route descriptions. |
+| `routeAllocation` | Structured split, hop, adapter, and pool-specific route allocation. V4 PoolKey data is encoded in the executable transaction and must not be reconstructed client-side. |
+| `fromTokenTax`, `toTokenTax` | Detected tax metadata. |
+| `effectiveSlippageBps` | Slippage plus applicable tax buffers. |
+| `tx` | Fee-on-input transaction; present when `sender` is supplied. |
+| `txFeeOnOutput` | Fee-on-output transaction; present when `sender` is supplied. |
+
+Treat the response as authoritative. Do not recalculate output taxes, route
+splits, minimum output, or calldata in the client.
+
+## Error handling
+
+The API can return an `{ "error": "..." }` object for validation or routing
+failures. Check both the HTTP status and the response body before using quote
+fields.
+
+Common Robinhood errors include:
+
+- Missing or unsupported `network`.
+- Invalid token, sender, receiver, or partner address.
+- Invalid raw amount, slippage, fee, gas price, or adapter filter.
+- A tax-token quote explicitly excluded the Uniswap V2 adapter.
+- No viable route across the currently active adapters, or insufficient liquidity.
+- RPC timeout or public-RPC rate limiting.
+- Missing executable transaction because `sender` was omitted.
+
+On-chain reverts can still occur if allowance, wallet balance, slippage,
+liquidity, token tax, or chain state changes after quoting. Fetch a fresh quote
+before retrying rather than resubmitting stale calldata.
+
+## Partner fee sharing
+
+Pass `fee` in basis points and `partnerAddress` in the quote request. The chosen
+fee mode determines the fee token:
+
+- `feeOnOutput=false`: collect from the input token and submit `quote.tx`.
+- `feeOnOutput=true`: collect from the output token and submit
+  `quote.txFeeOnOutput`.
+
+Always pass `feeOnOutput` while quoting so routing and
+`expectedOutputAmount` match the transaction variant you will execute. Partner
+fee eligibility and revenue share are controlled by the API-key agreement; do
+not assume that supplying an address alone enables sharing.
+
+## Tokens and routing
+
+### Curated frontend token list
+
+The token dropdown contains the following ERC-20 tokens. Native ETH is merged
+into the UI separately from this list.
+
+| Symbol | Name | Address | Decimals |
+|---|---|---|---:|
+| WETH | Wrapped Ether | `0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73` | 18 |
+| USDG | Global Dollar | `0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168` | 6 |
+| VIRTUAL | Virtuals Protocol | `0xc6911796042b15d7Fa4F6CDe69e245DdCd3d9c31` | 18 |
+| CASHCAT | Cash Cat | `0x020bfC650A365f8BB26819deAAbF3E21291018b4` | 18 |
+| WALLET | Robinhood Wallet | `0x0339f5459FC690aC85F1782e15782A151b4A9E1b` | 18 |
+| seedcoin | watch it grow | `0xD8d1C08A8bA4fc64BAC744f74290B89ADcb6Bf25` | 18 |
+| JUGGERNAUT | The Juggernaut | `0xD7321801CAae694090694Ff55A9323139F043B88` | 18 |
+| HOODRAT | Hoodrat | `0x8e62F281f282686fCa6dCB39288069a93fC23F1c` | 18 |
+| DIH | Dog In Hood | `0x17bb0C898254406b1Ea2e8E99B0C263e26c9E4a4` | 18 |
+| KITSU | KITSU | `0x8d4dFaaA4198b6486E0293Fec914C2B6a821D4DC` | 18 |
+| WEN | Wen Lambo | `0xA80eb66b3E0CF66ccB46f8b8C9e7ff5803eEb820` | 18 |
+| REPE | Robinhood Pepe | `0x5266eeafF092D6136AB63D18B975A60a0Cc0C8f7` | 18 |
+| TENDIES | TENDIES | `0x45242320DBB855EeA8Fd36804C6487E10E97FCF9` | 18 |
+| GME | GameStop | `0x7e86381A763F0Ecca2bDF27C54eAC403ddD48123` | 18 |
+| 4663 | 4663 | `0xd4052415613B34Af236024B895574c467f65b6dD` | 18 |
+| MARIAN | Lady Marian | `0x01637b14B7378B99dE75A64d50656d98488D9a4d` | 18 |
+
+The ordered list is exported as `ROBINHOOD_FRONTEND_TOKEN_LIST`.
+
+These community tokens are frontend conveniences, not an endorsement or a
+guarantee of liquidity, price stability, tax behavior, or contract safety.
+Always identify tokens by address and obtain a fresh quote and tax check.
+
+### Routing configuration
+
+Switch currently evaluates:
+
+- Uniswap V2 adapter index `0`.
+- Uniswap V3 adapter index `1`.
+- V3 fee tiers `100`, `500`, `3000`, and `10000`.
+- Trusted routing hubs WETH, USDG, VIRTUAL, and CASHCAT.
+
+The prepared V4 integration reserves adapter index `2`. Once activated, it
+discovers hookless static-fee V4 pools by complete `PoolKey` rather than
+applying the V3 fee-tier list. Native-ETH V4 currencies are normalized through the WETH/native
+alias described above. Until `/swap/adapters` returns index `2`, V4 is not part
+of live production quotes.
+
+If either side is detected as a transfer-tax token, the backend restricts the
+entire route (including every split and intermediate hop) to Uniswap V2. V3 is
+not considered for that quote, and V4 will remain excluded after activation.
+
+The API may split a quote across routes and adapters. Integrators should render
+the returned `paths` or `routeAllocation` instead of assuming a single path.
+
+## Rate limits
+
+Rate limits are assigned to the API key. A `429` response means the integration
+must back off. Use request coalescing and short-lived UI caching, avoid polling
+unchanged quotes, and debounce amount input before requesting a new route.
+
+For server integrations, contact Switch to coordinate the expected request
+rate and IP allowlisting. Do not distribute one production key across
+untrusted clients.
+
+## Current limitations
+
+- Robinhood limit orders are not deployed.
+- Rialto DEX is not integrated.
+- The production router supports Uniswap V2, V3, and supported hookless
+  static-fee V4 liquidity. V4 participates in quotes whenever adapter index
+  `2` is advertised by `/swap/adapters`.
+- The first V4 phase intentionally excludes hooked and dynamic-fee pools.
+- A V4 allocation currently selects its best single PoolKey; intra-V4
+  multi-pool splitting is not yet enabled. V4 can still split against V2/V3.
+- Contract and token addresses must be treated as chain-specific.
+
+See the main [SDK reference](README.md) for authentication, partner fees,
+response types, error handling, and the complete swap API schema.
+
+## Support
+
+- Documentation: <https://docs.switch.win>
+- Website: <https://switch.win>
+- Quote API: <https://quote.switch.win>
+
+## License
+
+See [LICENSE](LICENSE).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@switch-win/sdk",
-  "version": "1.1.0",
-  "description": "Official integration kit for the Switch DEX Aggregator on PulseChain — types, constants, ABIs, limit orders, and examples",
+  "version": "1.2.1",
+  "description": "Official integration kit for the Switch DEX Aggregator on PulseChain and Robinhood Chain",
   "author": "BuildTheTech",
   "license": "MIT",
   "repository": {
@@ -13,6 +13,7 @@
     "dex",
     "aggregator",
     "pulsechain",
+    "robinhood-chain",
     "swap",
     "limit-order",
     "eip712",
@@ -26,6 +27,8 @@
     ".": "./src/index.ts",
     "./types": "./src/types.ts",
     "./constants": "./src/constants.ts",
+    "./networks": "./src/networks/index.ts",
+    "./networks/robinhood": "./src/networks/robinhood.ts",
     "./limit-orders": "./src/limit-orders.ts",
     "./abi": "./abi/SwitchRouterABI.json",
     "./abi/limit-order": "./abi/SwitchLimitOrderABI.json"
@@ -33,7 +36,8 @@
   "files": [
     "src/",
     "abi/",
-    "README.md"
+    "README.md",
+    "ROBINHOOD.md"
   ],
   "devDependencies": {
     "typescript": "^5.9.3"

package/src/index.ts

@@ -109,7 +109,29 @@ export {
   fetchLimitOrderStats,
 } from "./limit-orders.js";
 
-export type {
-  BuildLimitOrderOptions,
-  ListLimitOrdersOptions,
-} from "./limit-orders.js";
+export type {
+  BuildLimitOrderOptions,
+  ListLimitOrdersOptions,
+} from "./limit-orders.js";
+
+// Network-specific swap configuration
+export {
+  ROBINHOOD_NETWORK,
+  ROBINHOOD_CHAIN,
+  ROBINHOOD_NATIVE_ETH,
+  ROBINHOOD_SWITCH_CONTRACTS,
+  ROBINHOOD_UNISWAP_CONTRACTS,
+  ROBINHOOD_TOKENS,
+  ROBINHOOD_FRONTEND_TOKEN_LIST,
+  ROBINHOOD_FRONTEND_DEFAULT_TOKENS,
+  ROBINHOOD_TRUSTED_INTERMEDIATES,
+  ROBINHOOD_FEE_TOKEN_PRIORITY,
+  selectRobinhoodFeeOnOutput,
+  buildRobinhoodQuoteUrl,
+} from "./networks/robinhood.js";
+
+export type {
+  RobinhoodToken,
+  RobinhoodQuoteParams,
+  RobinhoodTaxInfo,
+} from "./networks/robinhood.js";

package/src/networks/index.ts

@@ -0,0 +1,20 @@
+export {
+  ROBINHOOD_NETWORK,
+  ROBINHOOD_CHAIN,
+  ROBINHOOD_NATIVE_ETH,
+  ROBINHOOD_SWITCH_CONTRACTS,
+  ROBINHOOD_UNISWAP_CONTRACTS,
+  ROBINHOOD_TOKENS,
+  ROBINHOOD_FRONTEND_TOKEN_LIST,
+  ROBINHOOD_FRONTEND_DEFAULT_TOKENS,
+  ROBINHOOD_TRUSTED_INTERMEDIATES,
+  ROBINHOOD_FEE_TOKEN_PRIORITY,
+  selectRobinhoodFeeOnOutput,
+  buildRobinhoodQuoteUrl,
+} from "./robinhood.js";
+
+export type {
+  RobinhoodToken,
+  RobinhoodQuoteParams,
+  RobinhoodTaxInfo,
+} from "./robinhood.js";

package/src/networks/robinhood.ts

@@ -0,0 +1,321 @@
+import { API_BASE } from "../constants.js";
+
+/** API network value used by Switch endpoints. */
+export const ROBINHOOD_NETWORK = "robinhood" as const;
+
+/** Robinhood Chain mainnet metadata. */
+export const ROBINHOOD_CHAIN = {
+  id: 4663,
+  name: "Robinhood Chain",
+  nativeCurrency: {
+    name: "Ether",
+    symbol: "ETH",
+    decimals: 18,
+  },
+  rpcUrls: ["https://rpc.mainnet.chain.robinhood.com"],
+  blockExplorerUrl: "https://robinhoodchain.blockscout.com",
+} as const;
+
+/** Native-ETH sentinel accepted by the Switch quote API. */
+export const ROBINHOOD_NATIVE_ETH =
+  "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+
+/** Switch contracts deployed on Robinhood Chain. */
+export const ROBINHOOD_SWITCH_CONTRACTS = {
+  /** ERC-20 approval target. Use quote.tx.to when submitting a swap. */
+  router: "0x8730C3e2cF2c8CDa8E6166837A1Ed26f46aa9E59",
+  routerView: "0xFF6b56d3F444eB5b7FA1db047F57140C84810376",
+  uniswapV2Adapter: "0x7a14d7A8509a66209D4332843b983b29bF5604A4",
+  uniswapV3Adapter: "0xbcA08f296d9Ba0dc19Aa0E05D355365cE29A3205",
+  uniswapV4Adapter: "0x754dDCD05aFbAd1cc7Bc42B9268EB586F579E7F6",
+} as const;
+
+/** Uniswap contracts used by the Robinhood Switch deployment. */
+export const ROBINHOOD_UNISWAP_CONTRACTS = {
+  v2Factory: "0x8bcEaA40B9AcdfAedF85AdF4FF01F5Ad6517937f",
+  v3Factory: "0x1f7d7550B1b028f7571E69A784071F0205FD2EfA",
+  v3QuoterV2: "0x33e885eD0Ec9bF04EcfB19341582aADCb4c8A9E7",
+  v3SwapRouter02: "0xCaf681a66D020601342297493863E78C959E5cb2",
+  /** Canonical Uniswap V4 singleton and periphery deployments. */
+  v4PoolManager: "0x8366a39cc670b4001a1121b8f6a443a643e40951",
+  v4PositionDescriptor: "0x9639443158e8c5efa35bd45287bf2effd3d8dc06",
+  v4PositionManager: "0x58daec3116aae6d93017baaea7749052e8a04fa7",
+  v4Quoter: "0x8dc178efb8111bb0973dd9d722ebeff267c98f94",
+  v4StateView: "0xf3334192d15450cdd385c8b70e03f9a6bd9e673b",
+  v4UniversalRouter: "0x8876789976decbfcbbbe364623c63652db8c0904",
+  permit2: "0x000000000022D473030F116dDEE9F6B43aC78BA3",
+} as const;
+
+export interface RobinhoodToken {
+  readonly address: string;
+  readonly symbol: string;
+  readonly name: string;
+  readonly decimals: number;
+}
+
+/**
+ * Tokens in the Switch Robinhood frontend's curated list.
+ *
+ * Community-token addresses must never be selected by symbol alone; clones
+ * can share the same symbol. The addresses, symbols, and decimals below were
+ * checked against Robinhood Chain on 2026-07-11.
+ */
+export const ROBINHOOD_TOKENS = {
+  WETH: {
+    address: "0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73",
+    symbol: "WETH",
+    name: "Wrapped Ether",
+    decimals: 18,
+  },
+  USDG: {
+    address: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
+    symbol: "USDG",
+    name: "Global Dollar",
+    decimals: 6,
+  },
+  VIRTUAL: {
+    address: "0xc6911796042b15d7Fa4F6CDe69e245DdCd3d9c31",
+    symbol: "VIRTUAL",
+    name: "Virtuals Protocol",
+    decimals: 18,
+  },
+  CASHCAT: {
+    address: "0x020bfC650A365f8BB26819deAAbF3E21291018b4",
+    symbol: "CASHCAT",
+    name: "Cash Cat",
+    decimals: 18,
+  },
+  WALLET: {
+    address: "0x0339f5459FC690aC85F1782e15782A151b4A9E1b",
+    symbol: "WALLET",
+    name: "Robinhood Wallet",
+    decimals: 18,
+  },
+  SEEDCOIN: {
+    address: "0xD8d1C08A8bA4fc64BAC744f74290B89ADcb6Bf25",
+    symbol: "seedcoin",
+    name: "watch it grow",
+    decimals: 18,
+  },
+  JUGGERNAUT: {
+    address: "0xD7321801CAae694090694Ff55A9323139F043B88",
+    symbol: "JUGGERNAUT",
+    name: "The Juggernaut",
+    decimals: 18,
+  },
+  HOODRAT: {
+    address: "0x8e62F281f282686fCa6dCB39288069a93fC23F1c",
+    symbol: "HOODRAT",
+    name: "Hoodrat",
+    decimals: 18,
+  },
+  DIH: {
+    address: "0x17bb0C898254406b1Ea2e8E99B0C263e26c9E4a4",
+    symbol: "DIH",
+    name: "Dog In Hood",
+    decimals: 18,
+  },
+  KITSU: {
+    address: "0x8d4dFaaA4198b6486E0293Fec914C2B6a821D4DC",
+    symbol: "KITSU",
+    name: "KITSU",
+    decimals: 18,
+  },
+  WEN: {
+    address: "0xA80eb66b3E0CF66ccB46f8b8C9e7ff5803eEb820",
+    symbol: "WEN",
+    name: "Wen Lambo",
+    decimals: 18,
+  },
+  REPE: {
+    address: "0x5266eeafF092D6136AB63D18B975A60a0Cc0C8f7",
+    symbol: "REPE",
+    name: "Robinhood Pepe",
+    decimals: 18,
+  },
+  TENDIES: {
+    address: "0x45242320DBB855EeA8Fd36804C6487E10E97FCF9",
+    symbol: "TENDIES",
+    name: "TENDIES",
+    decimals: 18,
+  },
+  GME: {
+    address: "0x7e86381A763F0Ecca2bDF27C54eAC403ddD48123",
+    symbol: "GME",
+    name: "GameStop",
+    decimals: 18,
+  },
+  TOKEN_4663: {
+    address: "0xd4052415613B34Af236024B895574c467f65b6dD",
+    symbol: "4663",
+    name: "4663",
+    decimals: 18,
+  },
+  MARIAN: {
+    address: "0x01637b14B7378B99dE75A64d50656d98488D9a4d",
+    symbol: "MARIAN",
+    name: "Lady Marian",
+    decimals: 18,
+  },
+} as const satisfies Readonly<Record<string, RobinhoodToken>>;
+
+/** Exact ERC-20 ordering used by the Switch Robinhood token dropdown. */
+export const ROBINHOOD_FRONTEND_TOKEN_LIST = [
+  ROBINHOOD_TOKENS.WETH,
+  ROBINHOOD_TOKENS.USDG,
+  ROBINHOOD_TOKENS.VIRTUAL,
+  ROBINHOOD_TOKENS.CASHCAT,
+  ROBINHOOD_TOKENS.WALLET,
+  ROBINHOOD_TOKENS.SEEDCOIN,
+  ROBINHOOD_TOKENS.JUGGERNAUT,
+  ROBINHOOD_TOKENS.HOODRAT,
+  ROBINHOOD_TOKENS.DIH,
+  ROBINHOOD_TOKENS.KITSU,
+  ROBINHOOD_TOKENS.WEN,
+  ROBINHOOD_TOKENS.REPE,
+  ROBINHOOD_TOKENS.TENDIES,
+  ROBINHOOD_TOKENS.GME,
+  ROBINHOOD_TOKENS.TOKEN_4663,
+  ROBINHOOD_TOKENS.MARIAN,
+] as const satisfies readonly RobinhoodToken[];
+
+/**
+ * Tokens used to initialize the Robinhood swap UI.
+ *
+ * The current default pair is native ETH -> USDG. WETH remains in this set so
+ * native/wrapped lookup and token selection use the canonical deployment.
+ */
+export const ROBINHOOD_FRONTEND_DEFAULT_TOKENS = [
+  {
+    address: ROBINHOOD_NATIVE_ETH,
+    symbol: "ETH",
+    name: "Ether",
+    decimals: 18,
+  },
+  ROBINHOOD_TOKENS.WETH,
+  ROBINHOOD_TOKENS.USDG,
+] as const satisfies readonly RobinhoodToken[];
+
+/**
+ * Production trusted-hop addresses, ordered by routing usefulness.
+ *
+ * The 2026-07-11 audit enumerated every pool creation from the Robinhood
+ * Uniswap V2/V3 factories, then required multiple meaningful counterparties
+ * and a successful zero-tax simulation. Keep this list synchronized with the
+ * Robinhood backend routing configuration.
+ */
+export const ROBINHOOD_TRUSTED_INTERMEDIATES = [
+  ROBINHOOD_TOKENS.WETH.address,
+  ROBINHOOD_TOKENS.USDG.address,
+  ROBINHOOD_TOKENS.VIRTUAL.address,
+  ROBINHOOD_TOKENS.CASHCAT.address,
+] as const;
+
+/** Preferred Robinhood fee tokens, from highest to lowest priority. */
+export const ROBINHOOD_FEE_TOKEN_PRIORITY = [
+  ROBINHOOD_TOKENS.WETH.address,
+  ROBINHOOD_TOKENS.USDG.address,
+  ROBINHOOD_TOKENS.WALLET.address,
+  ROBINHOOD_TOKENS.SEEDCOIN.address,
+  ROBINHOOD_TOKENS.CASHCAT.address,
+] as const;
+
+const ROBINHOOD_FEE_PRIORITY_BY_ADDRESS = new Map<string, number>(
+  ROBINHOOD_FEE_TOKEN_PRIORITY.map((address, index) => [
+    address.toLowerCase(),
+    index + 1,
+  ]),
+);
+ROBINHOOD_FEE_PRIORITY_BY_ADDRESS.set(
+  ROBINHOOD_NATIVE_ETH.toLowerCase(),
+  1,
+);
+
+/** Minimum directional tax data required for fee-mode selection. */
+export interface RobinhoodTaxInfo {
+  isTaxToken: boolean;
+  buyTaxBps: number;
+  sellTaxBps: number;
+}
+
+/**
+ * Select the safer/preferred fee side for a Robinhood swap.
+ *
+ * Tax safety takes precedence over fee-token preference. Native ETH is treated
+ * as equivalent to WETH. `false` means fee on input; `true` means fee on output.
+ */
+export function selectRobinhoodFeeOnOutput(
+  from: string,
+  to: string,
+  fromTax: RobinhoodTaxInfo,
+  toTax: RobinhoodTaxInfo,
+): boolean {
+  const inputHasSellTax = fromTax.isTaxToken && fromTax.sellTaxBps > 0;
+  const outputHasBuyTax = toTax.isTaxToken && toTax.buyTaxBps > 0;
+
+  if (inputHasSellTax && outputHasBuyTax) return false;
+  if (outputHasBuyTax) return false;
+  if (inputHasSellTax) return true;
+
+  const inputPriority =
+    ROBINHOOD_FEE_PRIORITY_BY_ADDRESS.get(from.toLowerCase()) ?? Infinity;
+  const outputPriority =
+    ROBINHOOD_FEE_PRIORITY_BY_ADDRESS.get(to.toLowerCase()) ?? Infinity;
+
+  if (outputPriority < inputPriority) return true;
+  if (inputPriority < outputPriority) return false;
+  if (inputPriority !== Infinity) return true;
+  return false;
+}
+
+export interface RobinhoodQuoteParams {
+  from: string;
+  to: string;
+  /** Raw integer input amount in the input token's smallest unit. */
+  amount: string | bigint;
+  sender?: string;
+  receiver?: string;
+  /** Slippage in basis points. */
+  slippage?: number;
+  /** Partner fee in basis points. */
+  fee?: number;
+  partnerAddress?: string;
+  feeOnOutput?: boolean;
+  adapters?: string | readonly number[];
+}
+
+/** Build a Robinhood quote URL with the required network value included. */
+export function buildRobinhoodQuoteUrl(
+  params: RobinhoodQuoteParams,
+  apiBase: string = API_BASE,
+): string {
+  const query = new URLSearchParams({
+    network: ROBINHOOD_NETWORK,
+    from: params.from,
+    to: params.to,
+    amount: params.amount.toString(),
+  });
+
+  if (params.sender) query.set("sender", params.sender);
+  if (params.receiver) query.set("receiver", params.receiver);
+  if (params.slippage !== undefined) {
+    query.set("slippage", params.slippage.toString());
+  }
+  if (params.fee !== undefined) query.set("fee", params.fee.toString());
+  if (params.partnerAddress) {
+    query.set("partnerAddress", params.partnerAddress);
+  }
+  if (params.feeOnOutput !== undefined) {
+    query.set("feeOnOutput", params.feeOnOutput.toString());
+  }
+  if (params.adapters !== undefined) {
+    query.set(
+      "adapters",
+      Array.isArray(params.adapters)
+        ? params.adapters.join(",")
+        : String(params.adapters),
+    );
+  }
+
+  return `${apiBase.replace(/\/$/, "")}/swap/quote?${query.toString()}`;
+}

package/src/types.ts

@@ -116,8 +116,8 @@ export interface SwapTransaction {
   to: string;
   /** ABI-encoded `goSwitch()` calldata */
   data: string;
-  /** Native PLS to send (wei). `"0"` for ERC-20 input tokens. */
-  value: string;
+  /** Native currency to send (wei). `"0"` for ERC-20 input tokens. */
+  value: string;
 }
 
 // -- Human-readable paths --