@switch-win/sdk 1.2.0 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +81 -80
  2. package/ROBINHOOD.md +630 -518
  3. package/package.json +1 -1
  4. package/src/index.ts +26 -26
  5. package/src/limit-orders.ts +60 -30
  6. package/src/networks/index.ts +20 -20
  7. package/src/networks/robinhood.ts +327 -306
package/ROBINHOOD.md CHANGED
@@ -1,530 +1,642 @@
1
- # Switch SDK — Robinhood Chain
2
-
3
- Production integration reference for Switch swaps on Robinhood Chain mainnet.
4
-
5
- | Setting | Value |
6
- |---|---|
7
- | API network | `robinhood` |
8
- | Chain ID | `4663` |
9
- | Native currency | ETH (18 decimals) |
10
- | Public RPC | `https://rpc.mainnet.chain.robinhood.com` |
11
- | Explorer | `https://robinhoodchain.blockscout.com` |
12
- | Quote API | `https://quote.switch.win/swap/quote` |
13
- | Tax API | `https://quote.switch.win/swap/checkTax` |
14
- | Supported liquidity | Uniswap V2 and Uniswap V3 |
15
- | Limit orders | Not currently available |
16
-
17
- ## Contents
18
-
19
- - [Installation](#installation)
20
- - [Authentication](#authentication)
21
- - [Network configuration](#network-configuration)
22
- - [Contracts and native currency](#contracts-and-native-currency)
23
- - [Swap integration flow](#swap-integration-flow)
24
- - [Quickstart](#quickstart)
25
- - [Tax-token checks](#tax-token-checks)
26
- - [Selecting `feeOnOutput`](#selecting-feeonoutput)
27
- - [Approving and executing](#approving-and-executing)
28
- - [Swap API reference](#swap-api-reference)
29
- - [Error handling](#error-handling)
30
- - [Partner fee sharing](#partner-fee-sharing)
31
- - [Tokens and routing](#tokens-and-routing)
32
- - [Rate limits](#rate-limits)
33
- - [Current limitations](#current-limitations)
34
-
35
- ## Installation
36
-
37
- ```bash
38
- npm install @switch-win/sdk
39
- ```
40
-
41
- ```ts
42
- import {
43
- ROBINHOOD_CHAIN,
44
- ROBINHOOD_NATIVE_ETH,
45
- ROBINHOOD_SWITCH_CONTRACTS,
46
- ROBINHOOD_TOKENS,
47
- ROBINHOOD_FEE_TOKEN_PRIORITY,
48
- ROBINHOOD_FRONTEND_DEFAULT_TOKENS,
49
- ROBINHOOD_FRONTEND_TOKEN_LIST,
50
- buildRobinhoodQuoteUrl,
51
- type BestPathResponse,
52
- } from "@switch-win/sdk";
53
- ```
54
-
55
- The same exports are available from the smaller network entrypoint:
56
-
57
- ```ts
58
- import {
59
- ROBINHOOD_CHAIN,
60
- ROBINHOOD_TOKENS,
61
- buildRobinhoodQuoteUrl,
62
- } from "@switch-win/sdk/networks/robinhood";
63
- ```
64
-
65
- ## Authentication
66
-
67
- Every request to `quote.switch.win` requires a Switch API key in the
68
- `x-api-key` header:
69
-
70
- ```ts
71
- const headers = {
72
- "x-api-key": process.env.SWITCH_API_KEY!,
73
- };
74
- ```
75
-
76
- Do not expose a production API key in browser JavaScript. Browser applications
77
- should call a same-origin server route that attaches the key before forwarding
78
- the request to Switch.
79
-
80
- ## Network configuration
81
-
82
- `ROBINHOOD_CHAIN` can be adapted directly for most wallet libraries:
83
-
84
- ```ts
85
- const robinhoodWalletChain = {
86
- chainId: `0x${ROBINHOOD_CHAIN.id.toString(16)}`,
87
- chainName: ROBINHOOD_CHAIN.name,
88
- nativeCurrency: ROBINHOOD_CHAIN.nativeCurrency,
89
- rpcUrls: [...ROBINHOOD_CHAIN.rpcUrls],
90
- blockExplorerUrls: [ROBINHOOD_CHAIN.blockExplorerUrl],
91
- };
92
-
93
- await window.ethereum.request({
94
- method: "wallet_addEthereumChain",
95
- params: [robinhoodWalletChain],
96
- });
97
- ```
98
-
99
- ## Contracts and native currency
100
-
101
- ### Switch deployment
102
-
103
- | Contract | Address |
104
- |---|---|
105
- | SwitchRouter | `0x8730C3e2cF2c8CDa8E6166837A1Ed26f46aa9E59` |
106
- | SwitchRouterView | `0xFF6b56d3F444eB5b7FA1db047F57140C84810376` |
107
- | Uniswap V2 adapter | `0x7a14d7A8509a66209D4332843b983b29bF5604A4` |
108
- | Uniswap V3 adapter | `0xbcA08f296d9Ba0dc19Aa0E05D355365cE29A3205` |
109
-
110
- The router constant is the ERC-20 approval target. Always submit the swap to
111
- `quote.tx.to`; do not replace the API-provided transaction target with a
112
- hardcoded address.
113
-
114
- ### Native ETH and WETH
115
-
116
- Use `ROBINHOOD_NATIVE_ETH` when the user is selling or buying native ETH:
117
-
118
- ```text
119
- 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
120
- ```
121
-
122
- Use `ROBINHOOD_TOKENS.WETH.address` for the wrapped ERC-20:
123
-
124
- ```text
125
- 0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73
126
- ```
127
-
1
+ # Switch SDK — Robinhood Chain
2
+
3
+ Production integration reference for Switch swaps on Robinhood Chain mainnet.
4
+
5
+ | Setting | Value |
6
+ |---|---|
7
+ | API network | `robinhood` |
8
+ | Chain ID | `4663` |
9
+ | Native currency | ETH (18 decimals) |
10
+ | Public RPC | `https://rpc.mainnet.chain.robinhood.com` |
11
+ | Explorer | `https://robinhoodchain.blockscout.com` |
12
+ | Quote API | `https://quote.switch.win/swap/quote` |
13
+ | Tax API | `https://quote.switch.win/swap/checkTax` |
14
+ | Supported liquidity | Uniswap V2, V3, and hookless static-fee V4 |
15
+ | Limit orders | Not currently available |
16
+
17
+ ## Contents
18
+
19
+ - [Installation](#installation)
20
+ - [Authentication](#authentication)
21
+ - [Network configuration](#network-configuration)
22
+ - [Contracts and native currency](#contracts-and-native-currency)
23
+ - [Uniswap V4 routing](#uniswap-v4-routing)
24
+ - [Swap integration flow](#swap-integration-flow)
25
+ - [Quickstart](#quickstart)
26
+ - [Tax-token checks](#tax-token-checks)
27
+ - [Selecting `feeOnOutput`](#selecting-feeonoutput)
28
+ - [Approving and executing](#approving-and-executing)
29
+ - [Swap API reference](#swap-api-reference)
30
+ - [Error handling](#error-handling)
31
+ - [Partner fee sharing](#partner-fee-sharing)
32
+ - [Tokens and routing](#tokens-and-routing)
33
+ - [Rate limits](#rate-limits)
34
+ - [Current limitations](#current-limitations)
35
+
36
+ ## Installation
37
+
38
+ ```bash
39
+ npm install @switch-win/sdk
40
+ ```
41
+
42
+ ```ts
43
+ import {
44
+ ROBINHOOD_CHAIN,
45
+ ROBINHOOD_NATIVE_ETH,
46
+ ROBINHOOD_SWITCH_CONTRACTS,
47
+ ROBINHOOD_UNISWAP_CONTRACTS,
48
+ ROBINHOOD_TOKENS,
49
+ ROBINHOOD_FEE_TOKEN_PRIORITY,
50
+ ROBINHOOD_FRONTEND_DEFAULT_TOKENS,
51
+ ROBINHOOD_FRONTEND_TOKEN_LIST,
52
+ buildRobinhoodQuoteUrl,
53
+ type BestPathResponse,
54
+ } from "@switch-win/sdk";
55
+ ```
56
+
57
+ The same exports are available from the smaller network entrypoint:
58
+
59
+ ```ts
60
+ import {
61
+ ROBINHOOD_CHAIN,
62
+ ROBINHOOD_TOKENS,
63
+ buildRobinhoodQuoteUrl,
64
+ } from "@switch-win/sdk/networks/robinhood";
65
+ ```
66
+
67
+ ## Authentication
68
+
69
+ Every request to `quote.switch.win` requires a Switch API key in the
70
+ `x-api-key` header:
71
+
72
+ ```ts
73
+ const headers = {
74
+ "x-api-key": process.env.SWITCH_API_KEY!,
75
+ };
76
+ ```
77
+
78
+ Do not expose a production API key in browser JavaScript. Browser applications
79
+ should call a same-origin server route that attaches the key before forwarding
80
+ the request to Switch.
81
+
82
+ ## Network configuration
83
+
84
+ `ROBINHOOD_CHAIN` can be adapted directly for most wallet libraries:
85
+
86
+ ```ts
87
+ const robinhoodWalletChain = {
88
+ chainId: `0x${ROBINHOOD_CHAIN.id.toString(16)}`,
89
+ chainName: ROBINHOOD_CHAIN.name,
90
+ nativeCurrency: ROBINHOOD_CHAIN.nativeCurrency,
91
+ rpcUrls: [...ROBINHOOD_CHAIN.rpcUrls],
92
+ blockExplorerUrls: [ROBINHOOD_CHAIN.blockExplorerUrl],
93
+ };
94
+
95
+ await window.ethereum.request({
96
+ method: "wallet_addEthereumChain",
97
+ params: [robinhoodWalletChain],
98
+ });
99
+ ```
100
+
101
+ ## Contracts and native currency
102
+
103
+ ### Switch deployment
104
+
105
+ | Contract | Address |
106
+ |---|---|
107
+ | SwitchRouter | `0x8730C3e2cF2c8CDa8E6166837A1Ed26f46aa9E59` |
108
+ | Uniswap V2 adapter | `0x7a14d7A8509a66209D4332843b983b29bF5604A4` |
109
+ | Uniswap V3 adapter | `0xbcA08f296d9Ba0dc19Aa0E05D355365cE29A3205` |
110
+ | Uniswap V4 adapter | `0x754dDCD05aFbAd1cc7Bc42B9268EB586F579E7F6` |
111
+ | SwitchLimitOrder | `0x752c50DDd3B426cAE3D7A995F313Ac74ac6B0230` |
112
+ | Native ETH flow | `0x029FfC6aF9112eA078f1D6f4a98826DDB2136cf6` |
113
+ | Switch Limit Order adapter (index 3) | `0x412F625072c10e58C619D1e0b3C95cd3d5689871` |
114
+
115
+ The V4 adapter was created in
116
+ [deployment transaction `0x60d5...34a7`](https://robinhoodchain.blockscout.com/tx/0x60d56466a8162a643a15ecde98322ec05ea23d44d03fbd817df4ddbaef4834a7)
117
+ and added to the router in
118
+ [activation transaction `0x405b...1098`](https://robinhoodchain.blockscout.com/tx/0x405b49619ebfe4d1a73eb2d4601d8d1e63ae3d6fff0cd811a96c17e146971098).
119
+
120
+ The router constant is the ERC-20 approval target. Always submit the swap to
121
+ `quote.tx.to`; do not replace the API-provided transaction target with a
122
+ hardcoded address.
123
+
124
+ ### Native ETH and WETH
125
+
126
+ Use `ROBINHOOD_NATIVE_ETH` when the user is selling or buying native ETH:
127
+
128
+ ```text
129
+ 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
130
+ ```
131
+
132
+ Use `ROBINHOOD_TOKENS.WETH.address` for the wrapped ERC-20:
133
+
134
+ ```text
135
+ 0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73
136
+ ```
137
+
128
138
  Native ETH does not require approval. WETH and every other ERC-20 input token
129
139
  must be approved for `ROBINHOOD_SWITCH_CONTRACTS.router`.
130
140
 
131
- ## Swap integration flow
141
+ ### Limit orders
132
142
 
133
- Use the same sequence as a PulseChain integration:
134
-
135
- 1. Check both tokens with `/swap/checkTax`.
136
- 2. Select `feeOnOutput` from the tax results and preferred fee-token order.
137
- 3. Request `/swap/quote` with `network=robinhood`, the selected fee mode, and
138
- `sender` when executable calldata is required.
139
- 4. Approve the API-provided router target for ERC-20 input tokens.
140
- 5. Submit `quote.tx` for fee-on-input or `quote.txFeeOnOutput` for
141
- fee-on-output.
142
- 6. Show `expectedOutputAmount`, `minAmountOut`, route allocation, and detected
143
- taxes to the user.
144
-
145
- Any swap involving a tax token is routed entirely through Uniswap V2. This
146
- also applies when both input and output are tax tokens.
147
-
148
- ## Quickstart
149
-
150
- `amount` is always a raw integer amount in the input token's smallest unit.
151
- The following requests a quote for `0.001 ETH -> USDG`:
152
-
153
- ```ts
154
- // This simple pair uses fee-on-input. See "Selecting feeOnOutput" below for
155
- // the recommended dynamic selection when community or tax tokens are involved.
156
- const feeOnOutput = false;
157
-
158
- const url = buildRobinhoodQuoteUrl({
159
- from: ROBINHOOD_NATIVE_ETH,
160
- to: ROBINHOOD_TOKENS.USDG.address,
161
- amount: 1_000_000_000_000_000n,
162
- sender: walletAddress,
163
- slippage: 50, // 0.50%, expressed in basis points
164
- feeOnOutput,
165
- });
166
-
167
- const response = await fetch(url, {
168
- headers: { "x-api-key": process.env.SWITCH_API_KEY! },
169
- });
170
-
171
- if (!response.ok) {
172
- throw new Error(`Switch quote failed: ${response.status}`);
173
- }
174
-
175
- const quote = (await response.json()) as BestPathResponse;
176
- const transaction = feeOnOutput ? quote.txFeeOnOutput : quote.tx;
177
-
178
- if (!transaction) {
179
- throw new Error("Quote did not include the selected transaction variant");
180
- }
181
- ```
182
-
183
- Equivalent curl request:
184
-
185
- ```bash
186
- curl -H "x-api-key: YOUR_KEY" \
187
- "https://quote.switch.win/swap/quote?network=robinhood&from=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&to=0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168&amount=1000000000000000&sender=0xYOUR_WALLET&slippage=50"
188
- ```
189
-
190
- Omit `sender` for a display-only quote. Fetch again with the sender immediately
191
- before execution to receive current transaction calldata.
192
-
193
- ## Tax-token checks
194
-
195
- Robinhood tokens can apply pair-specific transfer taxes. Check both input and
196
- output tokens before requesting or executing a swap:
197
-
198
- ```ts
199
- async function checkTax(token: string) {
200
- const query = new URLSearchParams({ network: "robinhood", token });
201
- const response = await fetch(
202
- `https://quote.switch.win/swap/checkTax?${query}`,
203
- { headers: { "x-api-key": process.env.SWITCH_API_KEY! } },
204
- );
205
-
206
- if (!response.ok) throw new Error(`Tax check failed: ${response.status}`);
207
- return response.json();
208
- }
209
-
210
- const [inputTax, outputTax] = await Promise.all([
211
- checkTax(tokenIn),
212
- checkTax(tokenOut),
213
- ]);
214
- ```
215
-
216
- The quote response also includes `fromTokenTax`, `toTokenTax`,
217
- `expectedOutputAmount`, and effective-slippage fields. Display these values to
218
- the user rather than estimating taxes locally.
219
-
220
- ## Selecting `feeOnOutput`
221
-
222
- `feeOnOutput` determines which side of the swap pays the Switch partner or
223
- protocol fee:
224
-
225
- | Value | Fee token | Transaction field |
226
- |---|---|---|
227
- | `false` | Input token | `quote.tx` |
228
- | `true` | Output token | `quote.txFeeOnOutput` |
229
-
230
- Choose the mode before requesting the executable quote and pass it to
231
- `buildRobinhoodQuoteUrl`. This keeps `expectedOutputAmount`, routing, and the
232
- transaction calldata aligned with the mode that will actually be submitted.
233
-
234
- For Robinhood Chain, the recommended selection order is:
235
-
236
- 1. If both sides are tax tokens, use fee-on-input (`false`) to avoid the extra
237
- output-token transfers required by fee-on-output.
238
- 2. If only the output token has buy tax, use fee-on-input (`false`) to avoid
239
- routing the taxed output through additional transfers.
240
- 3. If only the input token has sell tax, use fee-on-output (`true`) so the fee
241
- is collected in the non-tax output token.
242
- 4. Otherwise, prefer collecting tokens in this order: WETH (with native ETH
243
- treated equivalently), USDG, WALLET, SEEDCOIN, then CASHCAT.
244
- 5. If neither token is preferred, default to fee-on-input (`false`).
245
-
246
- The no-tax priority list is:
247
-
248
- | Priority | Token | Address |
249
- |---:|---|---|
250
- | 1 | WETH / native ETH | `0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73` / native sentinel |
251
- | 2 | USDG | `0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168` |
252
- | 3 | WALLET | `0x0339f5459FC690aC85F1782e15782A151b4A9E1b` |
253
- | 4 | SEEDCOIN | `0x58f693A30F124E59b125F7c7b837b0F6bbAF5a45` |
254
- | 5 | CASHCAT | `0x020bfC650A365f8BB26819deAAbF3E21291018b4` |
255
-
256
- The ordered ERC-20 addresses are exported as
257
- `ROBINHOOD_FEE_TOKEN_PRIORITY`. When neither side is taxed, the selector takes
258
- the fee from whichever side contains the higher-priority token. If neither
259
- side is listed, it defaults to fee-on-input.
143
+ Robinhood ERC-20 limit orders use the same EIP-712 `LimitOrder` structure as
144
+ PulseChain, with these network-specific domain values:
260
145
 
261
146
  ```ts
262
147
  import {
263
- buildRobinhoodQuoteUrl,
264
- selectRobinhoodFeeOnOutput,
265
- type BestPathResponse,
148
+ ROBINHOOD_LIMIT_ORDER_EIP712_DOMAIN,
149
+ ROBINHOOD_SWITCH_CONTRACTS,
266
150
  } from "@switch-win/sdk";
267
151
 
268
- const feeOnOutput = selectRobinhoodFeeOnOutput(
269
- tokenIn,
270
- tokenOut,
271
- inputTax,
272
- outputTax,
152
+ // { name: "SwitchLimitOrder", version: "2", chainId: 4663,
153
+ // verifyingContract: "0x752c...0230" }
154
+ await signer.signTypedData(
155
+ ROBINHOOD_LIMIT_ORDER_EIP712_DOMAIN,
156
+ LIMIT_ORDER_EIP712_TYPES,
157
+ order,
273
158
  );
274
-
275
- const quoteUrl = buildRobinhoodQuoteUrl({
276
- from: tokenIn,
277
- to: tokenOut,
278
- amount: amountIn,
279
- sender: walletAddress,
280
- slippage: 50,
281
- feeOnOutput,
282
- });
283
-
284
- const quoteResponse = await fetch(quoteUrl, {
285
- headers: { "x-api-key": process.env.SWITCH_API_KEY! },
286
- });
287
- if (!quoteResponse.ok) {
288
- throw new Error(`Switch quote failed: ${quoteResponse.status}`);
289
- }
290
-
291
- const quote = (await quoteResponse.json()) as BestPathResponse;
292
- const transaction = feeOnOutput ? quote.txFeeOnOutput : quote.tx;
293
- if (!transaction) {
294
- throw new Error("Quote did not include the selected transaction variant");
295
- }
296
- ```
297
-
298
- Do not request one fee mode and submit the other transaction variant. Taxed
299
- output tokens are especially important: `feeOnOutput=true` makes the router
300
- receive and redistribute the output, which can trigger additional transfer-tax
301
- events.
302
-
303
- ## Approving and executing
304
-
305
- For ERC-20 input:
306
-
307
- ```ts
308
- const token = new ethers.Contract(
309
- tokenIn,
310
- ["function approve(address spender, uint256 amount) returns (bool)"],
311
- signer,
312
- );
313
-
314
- await (
315
- await token.approve(ROBINHOOD_SWITCH_CONTRACTS.router, amountIn)
316
- ).wait();
317
- ```
318
-
319
- Then submit the transaction returned by the API:
320
-
321
- ```ts
322
- await signer.sendTransaction({
323
- to: transaction.to,
324
- data: transaction.data,
325
- value: transaction.value,
326
- });
327
- ```
328
-
329
- For native ETH input, skip approval and send the API-provided `value`.
330
-
331
- ## Swap API reference
332
-
333
- All amounts are raw integer strings in the token's smallest unit. All token and
334
- wallet values are EVM addresses.
335
-
336
- ### List adapters
337
-
338
- ```http
339
- GET https://quote.switch.win/swap/adapters?network=robinhood
340
- x-api-key: YOUR_KEY
341
- ```
342
-
343
- Robinhood currently returns:
344
-
345
- | Index | Adapter |
346
- |---:|---|
347
- | `0` | Uniswap V2 |
348
- | `1` | Uniswap V3 |
349
-
350
- Do not permanently hard-code the available adapter list in an integration.
351
- Fetch it when presenting routing-source controls. If a quote involves a tax
352
- token, the backend overrides routing to tax-safe adapter `0`; an explicit
353
- filter that excludes adapter `0` is rejected.
354
-
355
- ### Check token tax
356
-
357
- ```http
358
- GET https://quote.switch.win/swap/checkTax?network=robinhood&token=0xTOKEN
359
- ```
360
-
361
- Example response:
362
-
363
- ```json
364
- {
365
- "token": "0x...",
366
- "isTaxToken": true,
367
- "buyTaxBps": 500,
368
- "sellTaxBps": 300
369
- }
370
- ```
371
-
372
- `500` basis points is `5%`. Use the input token's `sellTaxBps` and the output
373
- token's `buyTaxBps`. When both tokens are taxed, use fee-on-input.
374
-
375
- ### Get swap quote
376
-
377
- ```http
378
- GET https://quote.switch.win/swap/quote
379
159
  ```
380
160
 
381
- | Query parameter | Required | Description |
382
- |---|:---:|---|
383
- | `network` | Yes | Must be `robinhood`. |
384
- | `from` | Yes | Input token address or `ROBINHOOD_NATIVE_ETH`. |
385
- | `to` | Yes | Output token address or `ROBINHOOD_NATIVE_ETH`. |
386
- | `amount` | Yes | Raw input amount. |
387
- | `sender` | No | Required when transaction calldata is needed. |
388
- | `receiver` | No | Output recipient; defaults to `sender`. |
389
- | `slippage` | No | Basis points; default `50` (`0.5%`). |
390
- | `fee` | No | Partner/protocol fee in basis points. |
391
- | `partnerAddress` | No | Fee-sharing recipient. |
392
- | `feeOnOutput` | No | `true` takes the fee from output; `false` takes it from input. |
393
- | `adapters` | No | Comma-separated adapter indices, such as `0,1`. |
394
- | `gasPrice` | No | Quote gas price in wei. |
395
-
396
- Omitting `sender` produces a display-only quote. Request a fresh executable
397
- quote with `sender` immediately before execution.
398
-
399
- ### Quote response
400
-
401
- Important response fields:
402
-
403
- | Field | Description |
404
- |---|---|
405
- | `fromToken`, `toToken` | Normalized pair addresses. |
406
- | `totalAmountIn` | Gross input amount. |
407
- | `totalAmountOut` | Raw pool output before taxes and Switch fees. |
408
- | `expectedOutputAmount` | Expected user receipt after tax and fee, before slippage. |
409
- | `minAmountOut` | Minimum output encoded into calldata. |
410
- | `paths` | Human-readable route descriptions. |
411
- | `routeAllocation` | Structured split, hop, adapter, and fee-tier allocation. |
412
- | `fromTokenTax`, `toTokenTax` | Detected tax metadata. |
413
- | `effectiveSlippageBps` | Slippage plus applicable tax buffers. |
414
- | `tx` | Fee-on-input transaction; present when `sender` is supplied. |
415
- | `txFeeOnOutput` | Fee-on-output transaction; present when `sender` is supplied. |
416
-
417
- Treat the response as authoritative. Do not recalculate output taxes, route
418
- splits, minimum output, or calldata in the client.
419
-
420
- ## Error handling
421
-
422
- The API can return an `{ "error": "..." }` object for validation or routing
423
- failures. Check both the HTTP status and the response body before using quote
424
- fields.
425
-
426
- Common Robinhood errors include:
427
-
428
- - Missing or unsupported `network`.
429
- - Invalid token, sender, receiver, or partner address.
430
- - Invalid raw amount, slippage, fee, gas price, or adapter filter.
431
- - A tax-token quote explicitly excluded the Uniswap V2 adapter.
432
- - No viable Uniswap V2/V3 route or insufficient liquidity.
433
- - RPC timeout or public-RPC rate limiting.
434
- - Missing executable transaction because `sender` was omitted.
435
-
436
- On-chain reverts can still occur if allowance, wallet balance, slippage,
437
- liquidity, token tax, or chain state changes after quoting. Fetch a fresh quote
438
- before retrying rather than resubmitting stale calldata.
439
-
440
- ## Partner fee sharing
441
-
442
- Pass `fee` in basis points and `partnerAddress` in the quote request. The chosen
443
- fee mode determines the fee token:
444
-
445
- - `feeOnOutput=false`: collect from the input token and submit `quote.tx`.
446
- - `feeOnOutput=true`: collect from the output token and submit
447
- `quote.txFeeOnOutput`.
448
-
449
- Always pass `feeOnOutput` while quoting so routing and
450
- `expectedOutputAmount` match the transaction variant you will execute. Partner
451
- fee eligibility and revenue share are controlled by the API-key agreement; do
452
- not assume that supplying an address alone enables sharing.
453
-
454
- ## Tokens and routing
455
-
456
- ### Curated frontend token list
457
-
458
- The token dropdown contains the following ERC-20 tokens. Native ETH is merged
459
- into the UI separately from this list.
460
-
461
- | Symbol | Name | Address | Decimals |
462
- |---|---|---|---:|
463
- | WETH | Wrapped Ether | `0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73` | 18 |
464
- | USDG | Global Dollar | `0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168` | 6 |
465
- | VIRTUAL | Virtuals Protocol | `0xc6911796042b15d7Fa4F6CDe69e245DdCd3d9c31` | 18 |
466
- | CASHCAT | Cash Cat | `0x020bfC650A365f8BB26819deAAbF3E21291018b4` | 18 |
467
- | WALLET | Robinhood Wallet | `0x0339f5459FC690aC85F1782e15782A151b4A9E1b` | 18 |
468
- | seedcoin | watch it grow | `0x58f693A30F124E59b125F7c7b837b0F6bbAF5a45` | 9 |
469
- | JUGGERNAUT | The Juggernaut | `0xD7321801CAae694090694Ff55A9323139F043B88` | 18 |
470
- | HOODRAT | Hoodrat | `0x8e62F281f282686fCa6dCB39288069a93fC23F1c` | 18 |
471
- | DIH | Dog In Hood | `0x17bb0C898254406b1Ea2e8E99B0C263e26c9E4a4` | 18 |
472
- | KITSU | KITSU | `0x8d4dFaaA4198b6486E0293Fec914C2B6a821D4DC` | 18 |
473
- | WEN | Wen Lambo | `0xA80eb66b3E0CF66ccB46f8b8C9e7ff5803eEb820` | 18 |
474
- | REPE | Robinhood Pepe | `0x5266eeafF092D6136AB63D18B975A60a0Cc0C8f7` | 18 |
475
- | TENDIES | TENDIES | `0x45242320DBB855EeA8Fd36804C6487E10E97FCF9` | 18 |
476
- | GME | GameStop | `0x7e86381A763F0Ecca2bDF27C54eAC403ddD48123` | 18 |
477
- | 4663 | 4663 | `0xd4052415613B34Af236024B895574c467f65b6dD` | 18 |
478
- | MARIAN | Lady Marian | `0x01637b14B7378B99dE75A64d50656d98488D9a4d` | 18 |
479
-
480
- The ordered list is exported as `ROBINHOOD_FRONTEND_TOKEN_LIST`.
481
-
482
- These community tokens are frontend conveniences, not an endorsement or a
483
- guarantee of liquidity, price stability, tax behavior, or contract safety.
484
- Always identify tokens by address and obtain a fresh quote and tax check.
485
-
486
- ### Routing configuration
487
-
488
- Switch currently evaluates:
489
-
490
- - Uniswap V2 adapter index `0`.
491
- - Uniswap V3 adapter index `1`.
492
- - V3 fee tiers `100`, `500`, `3000`, and `10000`.
493
- - Trusted routing hubs WETH, USDG, VIRTUAL, and CASHCAT.
494
-
495
- If either side is detected as a transfer-tax token, the backend restricts the
496
- entire route (including every split and intermediate hop) to Uniswap V2. V3 is
497
- not considered for that quote.
498
-
499
- The API may split a quote across routes and adapters. Integrators should render
500
- the returned `paths` or `routeAllocation` instead of assuming a single path.
501
-
502
- ## Rate limits
503
-
504
- Rate limits are assigned to the API key. A `429` response means the integration
505
- must back off. Use request coalescing and short-lived UI caching, avoid polling
506
- unchanged quotes, and debounce amount input before requesting a new route.
507
-
508
- For server integrations, contact Switch to coordinate the expected request
509
- rate and IP allowlisting. Do not distribute one production key across
510
- untrusted clients.
511
-
512
- ## Current limitations
513
-
514
- - Robinhood limit orders are not deployed.
515
- - Rialto DEX is not integrated.
516
- - Quotes currently use Uniswap V2 and V3 liquidity.
517
- - Contract and token addresses must be treated as chain-specific.
518
-
519
- See the main [SDK reference](README.md) for authentication, partner fees,
520
- response types, error handling, and the complete swap API schema.
521
-
522
- ## Support
523
-
524
- - Documentation: <https://docs.switch.win>
525
- - Website: <https://switch.win>
526
- - Quote API: <https://quote.switch.win>
527
-
528
- ## License
529
-
530
- See [LICENSE](LICENSE).
161
+ Submit signed orders to `POST /limit-orders?network=robinhood`. For
162
+ `feeOnOutput=false`, approve `ROBINHOOD_SWITCH_CONTRACTS.limitOrder`; for
163
+ `feeOnOutput=true`, approve `ROBINHOOD_SWITCH_CONTRACTS.router`.
164
+
165
+ Native ETH input orders are created on-chain through
166
+ `ROBINHOOD_SWITCH_CONTRACTS.nativeEthFlow` and are indexed from its events; do
167
+ not POST them as signed EOA orders. Native ETH output is represented by WETH in
168
+ the order with `unwrapOutput=true`.
169
+
170
+ ## Uniswap V4 routing
171
+
172
+ Switch's Robinhood V4 integration is designed for canonical Uniswap V4, whose
173
+ pools share one `PoolManager`. A V4 pool is identified by its complete
174
+ `PoolKey`:
175
+
176
+ ```ts
177
+ type PoolKey = {
178
+ currency0: string;
179
+ currency1: string;
180
+ fee: number;
181
+ tickSpacing: number;
182
+ hooks: string;
183
+ };
184
+ ```
185
+
186
+ Do not treat V4 pools as V3 pools with another fee-tier list. The `fee`,
187
+ `tickSpacing`, and `hooks` values are all part of pool identity, and Robinhood
188
+ V4 discovery must preserve the full key. The backend selects the key and
189
+ embeds adapter-specific route data in the quote; clients should submit the
190
+ returned transaction unchanged rather than reconstructing V4 calldata.
191
+
192
+ Phase one supports **hookless static-fee pools only** (`hooks` is the zero
193
+ address, hook data is empty, and the dynamic-fee flag is not set). Pools with
194
+ custom hooks or dynamic fees are not considered until their behavior and
195
+ required hook data have been explicitly reviewed and allowed. This restriction
196
+ does not reduce V2 or V3 routing coverage.
197
+
198
+ V4 can represent native ETH as the zero-address currency. Switch routes use
199
+ the canonical Robinhood WETH address, so the V4 adapter unwraps WETH when a
200
+ selected pool consumes native ETH and wraps native ETH when that pool produces
201
+ it. API callers should continue using `ROBINHOOD_NATIVE_ETH` for a native user
202
+ input/output and `ROBINHOOD_TOKENS.WETH.address` for the ERC-20.
203
+
204
+ The Robinhood Uniswap V4 adapter is deployed at
205
+ `0x754dDCD05aFbAd1cc7Bc42B9268EB586F579E7F6`, whitelisted in the production
206
+ SwitchRouter at adapter index `2`, and exported as
207
+ `ROBINHOOD_SWITCH_CONTRACTS.uniswapV4Adapter`. Continue treating
208
+ `GET /swap/adapters?network=robinhood` as the source of truth for the adapters
209
+ currently available from the quote backend.
210
+
211
+ The canonical Robinhood V4 infrastructure is available through
212
+ `ROBINHOOD_UNISWAP_CONTRACTS`:
213
+
214
+ | Contract | Address |
215
+ |---|---|
216
+ | PoolManager | `0x8366a39cc670b4001a1121b8f6a443a643e40951` |
217
+ | PositionDescriptor | `0x9639443158e8c5efa35bd45287bf2effd3d8dc06` |
218
+ | PositionManager | `0x58daec3116aae6d93017baaea7749052e8a04fa7` |
219
+ | Quoter | `0x8dc178efb8111bb0973dd9d722ebeff267c98f94` |
220
+ | StateView | `0xf3334192d15450cdd385c8b70e03f9a6bd9e673b` |
221
+ | Universal Router | `0x8876789976decbfcbbbe364623c63652db8c0904` |
222
+ | Permit2 | `0x000000000022D473030F116dDEE9F6B43aC78BA3` |
223
+
224
+ Tax-token safety is unchanged: if either side is detected as a transfer-tax
225
+ token, the complete route is restricted to Uniswap V2 adapter index `0`.
226
+ Uniswap V3 and V4 are both excluded from that quote.
227
+
228
+ ## Swap integration flow
229
+
230
+ Use the same sequence as a PulseChain integration:
231
+
232
+ 1. Check both tokens with `/swap/checkTax`.
233
+ 2. Select `feeOnOutput` from the tax results and preferred fee-token order.
234
+ 3. Request `/swap/quote` with `network=robinhood`, the selected fee mode, and
235
+ `sender` when executable calldata is required.
236
+ 4. Approve the API-provided router target for ERC-20 input tokens.
237
+ 5. Submit `quote.tx` for fee-on-input or `quote.txFeeOnOutput` for
238
+ fee-on-output.
239
+ 6. Show `expectedOutputAmount`, `minAmountOut`, route allocation, and detected
240
+ taxes to the user.
241
+
242
+ Any swap involving a tax token is routed entirely through Uniswap V2. This
243
+ also applies when both input and output are tax tokens.
244
+
245
+ ## Quickstart
246
+
247
+ `amount` is always a raw integer amount in the input token's smallest unit.
248
+ The following requests a quote for `0.001 ETH -> USDG`:
249
+
250
+ ```ts
251
+ // This simple pair uses fee-on-input. See "Selecting feeOnOutput" below for
252
+ // the recommended dynamic selection when community or tax tokens are involved.
253
+ const feeOnOutput = false;
254
+
255
+ const url = buildRobinhoodQuoteUrl({
256
+ from: ROBINHOOD_NATIVE_ETH,
257
+ to: ROBINHOOD_TOKENS.USDG.address,
258
+ amount: 1_000_000_000_000_000n,
259
+ sender: walletAddress,
260
+ slippage: 50, // 0.50%, expressed in basis points
261
+ feeOnOutput,
262
+ });
263
+
264
+ const response = await fetch(url, {
265
+ headers: { "x-api-key": process.env.SWITCH_API_KEY! },
266
+ });
267
+
268
+ if (!response.ok) {
269
+ throw new Error(`Switch quote failed: ${response.status}`);
270
+ }
271
+
272
+ const quote = (await response.json()) as BestPathResponse;
273
+ const transaction = feeOnOutput ? quote.txFeeOnOutput : quote.tx;
274
+
275
+ if (!transaction) {
276
+ throw new Error("Quote did not include the selected transaction variant");
277
+ }
278
+ ```
279
+
280
+ Equivalent curl request:
281
+
282
+ ```bash
283
+ curl -H "x-api-key: YOUR_KEY" \
284
+ "https://quote.switch.win/swap/quote?network=robinhood&from=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&to=0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168&amount=1000000000000000&sender=0xYOUR_WALLET&slippage=50"
285
+ ```
286
+
287
+ Omit `sender` for a display-only quote. Fetch again with the sender immediately
288
+ before execution to receive current transaction calldata.
289
+
290
+ ## Tax-token checks
291
+
292
+ Robinhood tokens can apply pair-specific transfer taxes. Check both input and
293
+ output tokens before requesting or executing a swap:
294
+
295
+ ```ts
296
+ async function checkTax(token: string) {
297
+ const query = new URLSearchParams({ network: "robinhood", token });
298
+ const response = await fetch(
299
+ `https://quote.switch.win/swap/checkTax?${query}`,
300
+ { headers: { "x-api-key": process.env.SWITCH_API_KEY! } },
301
+ );
302
+
303
+ if (!response.ok) throw new Error(`Tax check failed: ${response.status}`);
304
+ return response.json();
305
+ }
306
+
307
+ const [inputTax, outputTax] = await Promise.all([
308
+ checkTax(tokenIn),
309
+ checkTax(tokenOut),
310
+ ]);
311
+ ```
312
+
313
+ The quote response also includes `fromTokenTax`, `toTokenTax`,
314
+ `expectedOutputAmount`, and effective-slippage fields. Display these values to
315
+ the user rather than estimating taxes locally.
316
+
317
+ ## Selecting `feeOnOutput`
318
+
319
+ `feeOnOutput` determines which side of the swap pays the Switch partner or
320
+ protocol fee:
321
+
322
+ | Value | Fee token | Transaction field |
323
+ |---|---|---|
324
+ | `false` | Input token | `quote.tx` |
325
+ | `true` | Output token | `quote.txFeeOnOutput` |
326
+
327
+ Choose the mode before requesting the executable quote and pass it to
328
+ `buildRobinhoodQuoteUrl`. This keeps `expectedOutputAmount`, routing, and the
329
+ transaction calldata aligned with the mode that will actually be submitted.
330
+
331
+ For Robinhood Chain, the recommended selection order is:
332
+
333
+ 1. If both sides are tax tokens, use fee-on-input (`false`) to avoid the extra
334
+ output-token transfers required by fee-on-output.
335
+ 2. If only the output token has buy tax, use fee-on-input (`false`) to avoid
336
+ routing the taxed output through additional transfers.
337
+ 3. If only the input token has sell tax, use fee-on-output (`true`) so the fee
338
+ is collected in the non-tax output token.
339
+ 4. Otherwise, prefer collecting tokens in this order: WETH (with native ETH
340
+ treated equivalently), USDG, WALLET, SEEDCOIN, then CASHCAT.
341
+ 5. If neither token is preferred, default to fee-on-input (`false`).
342
+
343
+ The no-tax priority list is:
344
+
345
+ | Priority | Token | Address |
346
+ |---:|---|---|
347
+ | 1 | WETH / native ETH | `0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73` / native sentinel |
348
+ | 2 | USDG | `0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168` |
349
+ | 3 | WALLET | `0x0339f5459FC690aC85F1782e15782A151b4A9E1b` |
350
+ | 4 | SEEDCOIN | `0x58f693A30F124E59b125F7c7b837b0F6bbAF5a45` |
351
+ | 5 | CASHCAT | `0x020bfC650A365f8BB26819deAAbF3E21291018b4` |
352
+
353
+ The ordered ERC-20 addresses are exported as
354
+ `ROBINHOOD_FEE_TOKEN_PRIORITY`. When neither side is taxed, the selector takes
355
+ the fee from whichever side contains the higher-priority token. If neither
356
+ side is listed, it defaults to fee-on-input.
357
+
358
+ ```ts
359
+ import {
360
+ buildRobinhoodQuoteUrl,
361
+ selectRobinhoodFeeOnOutput,
362
+ type BestPathResponse,
363
+ } from "@switch-win/sdk";
364
+
365
+ const feeOnOutput = selectRobinhoodFeeOnOutput(
366
+ tokenIn,
367
+ tokenOut,
368
+ inputTax,
369
+ outputTax,
370
+ );
371
+
372
+ const quoteUrl = buildRobinhoodQuoteUrl({
373
+ from: tokenIn,
374
+ to: tokenOut,
375
+ amount: amountIn,
376
+ sender: walletAddress,
377
+ slippage: 50,
378
+ feeOnOutput,
379
+ });
380
+
381
+ const quoteResponse = await fetch(quoteUrl, {
382
+ headers: { "x-api-key": process.env.SWITCH_API_KEY! },
383
+ });
384
+ if (!quoteResponse.ok) {
385
+ throw new Error(`Switch quote failed: ${quoteResponse.status}`);
386
+ }
387
+
388
+ const quote = (await quoteResponse.json()) as BestPathResponse;
389
+ const transaction = feeOnOutput ? quote.txFeeOnOutput : quote.tx;
390
+ if (!transaction) {
391
+ throw new Error("Quote did not include the selected transaction variant");
392
+ }
393
+ ```
394
+
395
+ Do not request one fee mode and submit the other transaction variant. Taxed
396
+ output tokens are especially important: `feeOnOutput=true` makes the router
397
+ receive and redistribute the output, which can trigger additional transfer-tax
398
+ events.
399
+
400
+ ## Approving and executing
401
+
402
+ For ERC-20 input:
403
+
404
+ ```ts
405
+ const token = new ethers.Contract(
406
+ tokenIn,
407
+ ["function approve(address spender, uint256 amount) returns (bool)"],
408
+ signer,
409
+ );
410
+
411
+ await (
412
+ await token.approve(ROBINHOOD_SWITCH_CONTRACTS.router, amountIn)
413
+ ).wait();
414
+ ```
415
+
416
+ Then submit the transaction returned by the API:
417
+
418
+ ```ts
419
+ await signer.sendTransaction({
420
+ to: transaction.to,
421
+ data: transaction.data,
422
+ value: transaction.value,
423
+ });
424
+ ```
425
+
426
+ For native ETH input, skip approval and send the API-provided `value`.
427
+
428
+ ## Swap API reference
429
+
430
+ All amounts are raw integer strings in the token's smallest unit. All token and
431
+ wallet values are EVM addresses.
432
+
433
+ ### List adapters
434
+
435
+ ```http
436
+ GET https://quote.switch.win/swap/adapters?network=robinhood
437
+ x-api-key: YOUR_KEY
438
+ ```
439
+
440
+ Robinhood currently returns:
441
+
442
+ | Index | Adapter |
443
+ |---:|---|
444
+ | `0` | Uniswap V2 |
445
+ | `1` | Uniswap V3 |
446
+ | `2` | Uniswap V4 |
447
+
448
+ Treat the endpoint response, not this document, as the source of truth for
449
+ which adapters are currently selectable.
450
+
451
+ Do not permanently hard-code the available adapter list in an integration.
452
+ Fetch it when presenting routing-source controls. If a quote involves a tax
453
+ token, the backend overrides routing to tax-safe adapter `0`; an explicit
454
+ filter that excludes adapter `0` is rejected.
455
+
456
+ ### Check token tax
457
+
458
+ ```http
459
+ GET https://quote.switch.win/swap/checkTax?network=robinhood&token=0xTOKEN
460
+ ```
461
+
462
+ Example response:
463
+
464
+ ```json
465
+ {
466
+ "token": "0x...",
467
+ "isTaxToken": true,
468
+ "buyTaxBps": 500,
469
+ "sellTaxBps": 300
470
+ }
471
+ ```
472
+
473
+ `500` basis points is `5%`. Use the input token's `sellTaxBps` and the output
474
+ token's `buyTaxBps`. When both tokens are taxed, use fee-on-input.
475
+
476
+ ### Get swap quote
477
+
478
+ ```http
479
+ GET https://quote.switch.win/swap/quote
480
+ ```
481
+
482
+ | Query parameter | Required | Description |
483
+ |---|:---:|---|
484
+ | `network` | Yes | Must be `robinhood`. |
485
+ | `from` | Yes | Input token address or `ROBINHOOD_NATIVE_ETH`. |
486
+ | `to` | Yes | Output token address or `ROBINHOOD_NATIVE_ETH`. |
487
+ | `amount` | Yes | Raw input amount. |
488
+ | `sender` | No | Required when transaction calldata is needed. |
489
+ | `receiver` | No | Output recipient; defaults to `sender`. |
490
+ | `slippage` | No | Basis points; default `50` (`0.5%`). |
491
+ | `fee` | No | Partner/protocol fee in basis points. |
492
+ | `partnerAddress` | No | Fee-sharing recipient. |
493
+ | `feeOnOutput` | No | `true` takes the fee from output; `false` takes it from input. |
494
+ | `adapters` | No | Comma-separated indices returned by `/swap/adapters`, such as `0,1,2`. |
495
+ | `gasPrice` | No | Quote gas price in wei. |
496
+
497
+ Omitting `sender` produces a display-only quote. Request a fresh executable
498
+ quote with `sender` immediately before execution.
499
+
500
+ ### Quote response
501
+
502
+ Important response fields:
503
+
504
+ | Field | Description |
505
+ |---|---|
506
+ | `fromToken`, `toToken` | Normalized pair addresses. |
507
+ | `totalAmountIn` | Gross input amount. |
508
+ | `totalAmountOut` | Raw pool output before taxes and Switch fees. |
509
+ | `expectedOutputAmount` | Expected user receipt after tax and fee, before slippage. |
510
+ | `minAmountOut` | Minimum output encoded into calldata. |
511
+ | `paths` | Human-readable route descriptions. |
512
+ | `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. |
513
+ | `fromTokenTax`, `toTokenTax` | Detected tax metadata. |
514
+ | `effectiveSlippageBps` | Slippage plus applicable tax buffers. |
515
+ | `tx` | Fee-on-input transaction; present when `sender` is supplied. |
516
+ | `txFeeOnOutput` | Fee-on-output transaction; present when `sender` is supplied. |
517
+
518
+ Treat the response as authoritative. Do not recalculate output taxes, route
519
+ splits, minimum output, or calldata in the client.
520
+
521
+ ## Error handling
522
+
523
+ The API can return an `{ "error": "..." }` object for validation or routing
524
+ failures. Check both the HTTP status and the response body before using quote
525
+ fields.
526
+
527
+ Common Robinhood errors include:
528
+
529
+ - Missing or unsupported `network`.
530
+ - Invalid token, sender, receiver, or partner address.
531
+ - Invalid raw amount, slippage, fee, gas price, or adapter filter.
532
+ - A tax-token quote explicitly excluded the Uniswap V2 adapter.
533
+ - No viable route across the currently active adapters, or insufficient liquidity.
534
+ - RPC timeout or public-RPC rate limiting.
535
+ - Missing executable transaction because `sender` was omitted.
536
+
537
+ On-chain reverts can still occur if allowance, wallet balance, slippage,
538
+ liquidity, token tax, or chain state changes after quoting. Fetch a fresh quote
539
+ before retrying rather than resubmitting stale calldata.
540
+
541
+ ## Partner fee sharing
542
+
543
+ Pass `fee` in basis points and `partnerAddress` in the quote request. The chosen
544
+ fee mode determines the fee token:
545
+
546
+ - `feeOnOutput=false`: collect from the input token and submit `quote.tx`.
547
+ - `feeOnOutput=true`: collect from the output token and submit
548
+ `quote.txFeeOnOutput`.
549
+
550
+ Always pass `feeOnOutput` while quoting so routing and
551
+ `expectedOutputAmount` match the transaction variant you will execute. Partner
552
+ fee eligibility and revenue share are controlled by the API-key agreement; do
553
+ not assume that supplying an address alone enables sharing.
554
+
555
+ ## Tokens and routing
556
+
557
+ ### Curated frontend token list
558
+
559
+ The token dropdown contains the following ERC-20 tokens. Native ETH is merged
560
+ into the UI separately from this list.
561
+
562
+ | Symbol | Name | Address | Decimals |
563
+ |---|---|---|---:|
564
+ | WETH | Wrapped Ether | `0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73` | 18 |
565
+ | USDG | Global Dollar | `0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168` | 6 |
566
+ | VIRTUAL | Virtuals Protocol | `0xc6911796042b15d7Fa4F6CDe69e245DdCd3d9c31` | 18 |
567
+ | CASHCAT | Cash Cat | `0x020bfC650A365f8BB26819deAAbF3E21291018b4` | 18 |
568
+ | WALLET | Robinhood Wallet | `0x0339f5459FC690aC85F1782e15782A151b4A9E1b` | 18 |
569
+ | SEEDCOIN | Seedcoin | `0x58f693A30F124E59b125F7c7b837b0F6bbAF5a45` | 18 |
570
+ | JUGGERNAUT | The Juggernaut | `0xD7321801CAae694090694Ff55A9323139F043B88` | 18 |
571
+ | HOODRAT | Hoodrat | `0x8e62F281f282686fCa6dCB39288069a93fC23F1c` | 18 |
572
+ | DIH | Dog In Hood | `0x17bb0C898254406b1Ea2e8E99B0C263e26c9E4a4` | 18 |
573
+ | KITSU | KITSU | `0x8d4dFaaA4198b6486E0293Fec914C2B6a821D4DC` | 18 |
574
+ | WEN | Wen Lambo | `0xA80eb66b3E0CF66ccB46f8b8C9e7ff5803eEb820` | 18 |
575
+ | REPE | Robinhood Pepe | `0x5266eeafF092D6136AB63D18B975A60a0Cc0C8f7` | 18 |
576
+ | TENDIES | TENDIES | `0x45242320DBB855EeA8Fd36804C6487E10E97FCF9` | 18 |
577
+ | GME | GameStop | `0x7e86381A763F0Ecca2bDF27C54eAC403ddD48123` | 18 |
578
+ | 4663 | 4663 | `0xd4052415613B34Af236024B895574c467f65b6dD` | 18 |
579
+ | MARIAN | Lady Marian | `0x01637b14B7378B99dE75A64d50656d98488D9a4d` | 18 |
580
+
581
+ The ordered list is exported as `ROBINHOOD_FRONTEND_TOKEN_LIST`.
582
+
583
+ These community tokens are frontend conveniences, not an endorsement or a
584
+ guarantee of liquidity, price stability, tax behavior, or contract safety.
585
+ Always identify tokens by address and obtain a fresh quote and tax check.
586
+
587
+ ### Routing configuration
588
+
589
+ Switch currently evaluates:
590
+
591
+ - Uniswap V2 adapter index `0`.
592
+ - Uniswap V3 adapter index `1`.
593
+ - V3 fee tiers `100`, `500`, `3000`, and `10000`.
594
+ - Trusted routing hubs WETH, USDG, VIRTUAL, and CASHCAT.
595
+
596
+ The prepared V4 integration reserves adapter index `2`. Once activated, it
597
+ discovers hookless static-fee V4 pools by complete `PoolKey` rather than
598
+ applying the V3 fee-tier list. Native-ETH V4 currencies are normalized through the WETH/native
599
+ alias described above. Until `/swap/adapters` returns index `2`, V4 is not part
600
+ of live production quotes.
601
+
602
+ If either side is detected as a transfer-tax token, the backend restricts the
603
+ entire route (including every split and intermediate hop) to Uniswap V2. V3 is
604
+ not considered for that quote, and V4 will remain excluded after activation.
605
+
606
+ The API may split a quote across routes and adapters. Integrators should render
607
+ the returned `paths` or `routeAllocation` instead of assuming a single path.
608
+
609
+ ## Rate limits
610
+
611
+ Rate limits are assigned to the API key. A `429` response means the integration
612
+ must back off. Use request coalescing and short-lived UI caching, avoid polling
613
+ unchanged quotes, and debounce amount input before requesting a new route.
614
+
615
+ For server integrations, contact Switch to coordinate the expected request
616
+ rate and IP allowlisting. Do not distribute one production key across
617
+ untrusted clients.
618
+
619
+ ## Current limitations
620
+
621
+ - Robinhood limit orders are not deployed.
622
+ - Rialto DEX is not integrated.
623
+ - The production router supports Uniswap V2, V3, and supported hookless
624
+ static-fee V4 liquidity. V4 participates in quotes whenever adapter index
625
+ `2` is advertised by `/swap/adapters`.
626
+ - The first V4 phase intentionally excludes hooked and dynamic-fee pools.
627
+ - A V4 allocation currently selects its best single PoolKey; intra-V4
628
+ multi-pool splitting is not yet enabled. V4 can still split against V2/V3.
629
+ - Contract and token addresses must be treated as chain-specific.
630
+
631
+ See the main [SDK reference](README.md) for authentication, partner fees,
632
+ response types, error handling, and the complete swap API schema.
633
+
634
+ ## Support
635
+
636
+ - Documentation: <https://docs.switch.win>
637
+ - Website: <https://switch.win>
638
+ - Quote API: <https://quote.switch.win>
639
+
640
+ ## License
641
+
642
+ See [LICENSE](LICENSE).