@nonnux/world-swap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nonnux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# @nonnux/world-swap
+
+A drop-in **token swap** for [World App](https://world.org/world-app) mini apps —
+a ready-made swap card plus the quote API behind it. Routes through Uniswap
+**V2, V3 and cross-version** pools on **World Chain**, with a 1% platform fee.
+
+It's the same swap that powers the nonnux mini apps (UFO PIZZA SLICE, PAU$, REI$
+Slots, …), packaged so you can add it to your own mini app in a couple of lines.
+
+```
+┌──────────────────────────┐        ┌──────────────────────────────┐
+│  <SwapCard />  (client)   │ ─────▶ │  /api/swap/quote  (server)   │
+│  wallet · UI · tx via     │  POST  │  reads Uniswap V2/V3 via RPC │
+│  MiniKit.sendTransaction  │ ◀───── │  (ethers, no DB, no secrets) │
+└──────────────────────────┘        └──────────────────────────────┘
+```
+
+---
+
+## Requirements
+
+- A **Next.js** app (App Router) — it provides the API route.
+- **Tailwind CSS v4** — the card is styled with Tailwind utility classes.
+- Peer deps (you almost certainly already have these): `react`, `react-dom`,
+  `ethers@^6`, `@worldcoin/minikit-js@>=1.9`.
+
+## Install
+
+```bash
+npm install @nonnux/world-swap
+```
+
+Because the package ships source (not pre-bundled, for now), let Next transpile
+it — add this to `next.config.js`:
+
+```js
+const nextConfig = {
+  transpilePackages: ['@nonnux/world-swap'],
+};
+module.exports = nextConfig;
+```
+
+## Usage
+
+### 1. Mount the quote API
+
+Create `app/api/swap/quote/route.js`:
+
+```js
+// Batteries-included: nonnux token list + World Chain contracts.
+export { POST, GET } from '@nonnux/world-swap/server';
+```
+
+### 2. Render the card
+
+```jsx
+'use client';
+import { SwapCard } from '@nonnux/world-swap';
+import { Button } from '@/components/ui/Button'; // your own button
+
+export default function SwapTab({ user }) {
+  return <SwapCard walletUser={user} Button={Button} />;
+}
+```
+
+That's it. `walletUser` is your connected user object (`{ address }`); pass
+`null` to show the "connect your wallet" state. `Button` is your own button
+component so the CTA matches your app's look.
+
+> Token icons are loaded from `/<icon>` (e.g. `/tokens/slice.gif`) in your
+> `public/` folder. Copy the icons you need, or point `tokens[].icon` at a URL.
+
+---
+
+## Customising
+
+Everything is optional and falls back to the nonnux / World Chain defaults.
+
+### Your own token list
+
+`app/api/swap/quote/route.js`:
+
+```js
+import { createSwapQuoteHandler } from '@nonnux/world-swap/server';
+import { MY_TOKENS } from '@/config/tokens';
+
+export const { POST, GET } = createSwapQuoteHandler({ tokens: MY_TOKENS });
+```
+
+Component:
+
+```jsx
+import { SwapCard } from '@nonnux/world-swap';
+import { MY_TOKENS } from '@/config/tokens';
+
+<SwapCard walletUser={user} Button={Button} tokens={MY_TOKENS} />
+```
+
+A token looks like:
+
+```js
+{
+  symbol: 'SLICE',
+  name: 'UFO PIZZA',
+  address: '0x...',
+  icon: '/tokens/slice.gif',          // path in /public or a URL
+  gradient: 'from-orange-500 to-yellow-500', // Tailwind gradient
+  decimals: 18,
+  emoji: '🍕',                         // fallback if icon fails
+  externalTaxPercent: 0,              // token transfer tax, if any
+  poolVersion: 'v2',                  // 'v2' | 'v3'
+  v3FeeTier: 10000,                   // only for v3 tokens
+}
+```
+
+### `<SwapCard />` props
+
+| Prop             | Default                  | Description                                            |
+| ---------------- | ------------------------ | ------------------------------------------------------ |
+| `walletUser`     | —                        | Connected user `{ address }`. `null` → connect state.  |
+| `Button`         | —                        | Your button component for the CTA.                     |
+| `tokens`         | nonnux list              | Token list to swap between.                            |
+| `contracts`      | World Chain              | Override any contract address (merged with defaults).  |
+| `rpcUrl`         | Alchemy public           | JSON-RPC URL for balance reads.                        |
+| `apiBasePath`    | `/api/swap`              | Base path of your quote route (`${base}/quote`).       |
+| `explorerUrl`    | `https://worldscan.org`  | Block explorer for the "view tx" link.                 |
+| `ImageComponent` | `<img>`                  | Pass `next/image` (or a wrapper) to optimise icons.    |
+| `storagePrefix`  | `world_swap`             | localStorage key prefix (avoid cross-app collisions).  |
+| `title`          | `Swap`                   | Header title.                                          |
+
+### `createSwapQuoteHandler(config)` options
+
+`tokens`, `contracts`, `rpcUrl`, `directV3Pairs`, `platformFeeBps`, `v3FeeTiers`.
+
+---
+
+## How it works
+
+- **Quote** (`/api/swap/quote`, server): given a token pair + amount, it reads
+  Uniswap pools on World Chain via `ethers` and returns the best route
+  (direct V2, V2 multi-hop through WLD, direct V3, or V3↔V2 cross-version),
+  plus price impact and the min-received after fee.
+- **Swap** (client): builds a 2-step transaction (ERC-20 `transfer` to the swap
+  contract, then the swap call) and submits it with
+  `MiniKit.commandsAsync.sendTransaction`. The contract enforces `minAmountOut`.
+
+No database, no API keys, no env vars required — the quote route only needs a
+public World Chain RPC.
+
+---
+
+## Add this swap to your own mini app
+
+Building a World App mini app and want a swap tab without writing one? Install
+`@nonnux/world-swap`, mount the quote route, and drop in `<SwapCard />` — about
+two lines each (see **Usage** above). Bring your own token list or use the
+defaults.
+
+**Need a hand?** Read the guide: https://github.com/nonnux/world-swap#readme
+
+---
+
+## License
+
+MIT © nonnux

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@nonnux/world-swap",
+  "version": "0.1.0",
+  "description": "Drop-in token swap card + quote API for World App mini apps (Uniswap V2/V3 on World Chain).",
+  "keywords": [
+    "worldcoin",
+    "world-app",
+    "minikit",
+    "worldchain",
+    "uniswap",
+    "swap",
+    "defi",
+    "react",
+    "nextjs"
+  ],
+  "license": "MIT",
+  "author": "nonnux",
+  "homepage": "https://github.com/nonnux/world-swap#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nonnux/world-swap.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/client.js",
+    "./server": "./src/server.js",
+    "./defaults": "./src/defaults.js"
+  },
+  "peerDependencies": {
+    "@worldcoin/minikit-js": ">=1.9",
+    "ethers": "^6",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "@worldcoin/minikit-js": {
+      "optional": false
+    }
+  }
+}