> For the complete documentation index, see [llms.txt](https://docs.evently.market/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.evently.market/developers/frontend.md).

# Frontend Integration

## Stack

| Layer               | Tech                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------- |
| Framework           | Next.js 14 (App Router)                                                               |
| Styling             | Tailwind CSS + CSS variables                                                          |
| Web3                | wagmi v2 + viem                                                                       |
| Auth & Wallets      | Privy (`@privy-io/react-auth`) + MOSS Wallet (`@megaeth-labs/wallet-wagmi-connector`) |
| Account Abstraction | ERC-4337 via Privy smart wallets + Pimlico bundler                                    |
| Database            | Supabase                                                                              |
| Bridge/Swap         | LiFi SDK                                                                              |
| Fonts               | Geist Sans + JetBrains Mono                                                           |

***

## Key Files

| File                                      | Purpose                                                 |
| ----------------------------------------- | ------------------------------------------------------- |
| `frontend/app/layout.tsx`                 | Root layout — metadata, OG tags, JSON-LD, fonts         |
| `frontend/app/providers.tsx`              | PrivyProvider + SmartWalletsProvider + WagmiProvider    |
| `frontend/app/page.tsx`                   | Landing page — hero, ticker, CTAs                       |
| `frontend/app/markets/page.tsx`           | Markets list                                            |
| `frontend/app/markets/[id]/page.tsx`      | Market detail + trade panel                             |
| `frontend/app/markets/create/page.tsx`    | Create market form                                      |
| `frontend/components/Header.tsx`          | Top nav with evently wordmark                           |
| `frontend/components/EventlyLogo.tsx`     | evently icon (M+E Heart) + wordmark                     |
| `frontend/components/MarketModal.tsx`     | Trade panel — buy/sell YES/NO shares                    |
| `frontend/components/QuickTradePanel.tsx` | Floating quick trade drawer                             |
| `frontend/components/LiveFeed.tsx`        | Real-time trade feed                                    |
| `frontend/config/privy.ts`                | Privy app config (login methods, embedded wallet)       |
| `frontend/config/markets.ts`              | Contract addresses + ABI                                |
| `frontend/config/wagmi.ts`                | Wagmi chain config                                      |
| `frontend/lib/paymaster.ts`               | Bundler/paymaster clients, sponsored function whitelist |
| `frontend/hooks/useSmartAccount.ts`       | Unified wallet hook — gasless + EOA fallback            |
| `frontend/hooks/useSessionKeys.ts`        | Session key lifecycle (sign once, trade up to 100×)     |

***

## Authentication & Wallets (Privy)

evently uses [Privy](https://privy.io) for authentication. Users sign in with email or social accounts — no wallet extension required.

**Supported login methods:** Email · Google · Twitter · Discord · GitHub · Apple · External wallets (MetaMask, Rabby, Coinbase Wallet, Rainbow)

On first login, Privy automatically creates an **embedded wallet** (EOA) in the background. This is then wrapped in an **ERC-4337 Kernel smart account** for gasless transactions.

```tsx
// frontend/app/providers.tsx
import { PrivyProvider } from "@privy-io/react-auth";
import { SmartWalletsProvider } from "@privy-io/react-auth/smart-wallets";

<PrivyProvider appId={PRIVY_APP_ID} config={privyConfig}>
  <SmartWalletsProvider config={smartWalletsConfig}>
    {/* wagmi + app */}
  </SmartWalletsProvider>
</PrivyProvider>
```

### MOSS Wallet (MegaETH embedded SDK)

Privy coexists with the **MOSS Wallet SDK** — MegaETH's native embedded wallet. The MOSS wagmi connector is registered in `providers.tsx` and is selectable via any standard wagmi `useConnect()` flow.

* Package: [`@megaeth-labs/wallet-wagmi-connector`](https://www.npmjs.com/package/@megaeth-labs/wallet-wagmi-connector)
* Connector id: `mossWallet` · rdns: `com.megaeth.account`
* Network is fixed per instance — evently pins MOSS to mainnet (chain `4326`)
* Quickstart: [docs.megaeth.com/moss-docs/wallet/quickstart](https://docs.megaeth.com/moss-docs/wallet/quickstart)
* Full reference: [docs.megaeth.com/moss-docs](https://docs.megaeth.com/moss-docs)

```tsx
// frontend/app/providers.tsx
import { megaWallet } from "@megaeth-labs/wallet-wagmi-connector";

const wagmiConfig = createConfig({
  chains: [megaethMainnet, megaethTestnet],
  connectors: [megaWallet({ network: "mainnet" })],
  transports: { /* … */ },
});
```

```tsx
// Anywhere in the app
import { useConnect } from "wagmi";

const { connect, connectors } = useConnect();
const moss = connectors.find((c) => c.id === "mossWallet");

<button onClick={() => moss && connect({ connector: moss })}>
  Connect MOSS Wallet
</button>
```

MOSS exposes additional MegaETH-native methods through the EIP-1193 provider (`wallet_balances`, `wallet_swap`, `wallet_grantPermissions`, …) — useful for paymaster setup, smart approvals, and the policy engine. See the [Methods Reference](https://docs.megaeth.com/moss-docs/methods/methods) and [Paymaster Guide](https://docs.megaeth.com/moss-docs/wallet/paymaster-setup) upstream.

***

## Gas Sponsorship

Core Evently operations are gasless. The protocol sponsors gas via a **Pimlico paymaster** (ERC-4337).

Sponsored functions: `placeOrder`, `sellToAMM`, `createMarket`, `resolveMarket`, `claimRewards`, `approve` (USDM).

```tsx
import { useSmartAccount } from "@/hooks/useSmartAccount";

const { sendGasless } = useSmartAccount();

// User never pays gas — routed through bundler + paymaster
await sendGasless({
  to: MARKETS_ADDRESS,
  abi: MARKETS_ABI,
  functionName: "placeOrder",
  args: [marketId, optionIdx, side, quantity, price, minFill],
});
```

See `frontend/lib/paymaster.ts` for the full whitelist and rate-limiting logic.

***

## Logo Component

The evently logo is rendered via the `EventlyLogo` component:

```tsx
import { EventlyLogo } from "@/components/EventlyLogo";

// Icon only — adapts to currentColor (dark/light)
<EventlyLogo size={32} />

// With dark background
<EventlyLogo size={32} withBg />
```

**Wordmark** — "event" in `#19191A` (dark), "ly" in `#70BAD2` (blue):

```tsx
<span>
  <span style={{ color: "var(--t1)" }}>event</span>
  <span style={{ color: "#70BAD2" }}>ly</span>
</span>
```

***

## Brand Colors

```tsx
// Tailwind custom colors (tailwind.config.js)
colors: {
  "mega-pink":  "#F786C6",  // Create market only
  "mega-blue":  "#70BAD2",  // Primary accent / logo "ly"
  "mega-green": "#6DD0A9",  // Buy / Yes / action
}

// CSS variables
"--pink":  "#F786C6"
"--blue":  "#70BAD2"
"--green": "#6DD0A9"
"--t1":    "#19191A"  // Primary text (light mode)
"--t2":    "#52525b"  // Secondary text
```

***

## MegaETH Chain Config (wagmi)

```ts
import { defineChain } from "viem";

export const megaEth = defineChain({
  id: 4326,
  name: "MegaETH Mainnet",
  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
  rpcUrls: {
    default: { http: ["https://mainnet.megaeth.com/rpc"] },
  },
  blockExplorers: {
    default: { name: "Blockscout", url: "https://megaeth.blockscout.com" },
  },
});
```

***

## Real-Time Events (MegaETH \~10ms blocks)

Use `watchContractEvent` for live trade feed — critical for MegaETH's \~10ms block finality:

```ts
import { useWatchContractEvent } from "wagmi";

useWatchContractEvent({
  address: MARKETS_ADDRESS,
  abi: MARKETS_ABI,
  eventName: "OrderFilled",
  onLogs(logs) {
    // Update live feed — fires every ~10ms block
    setTrades(prev => [...logs.map(parseTrade), ...prev].slice(0, 50));
  },
});
```

***

## Wiring Checklist

* [ ] `getImpliedPrices(marketId)` — display live YES/NO probabilities
* [ ] `quoteBuy(marketId, optionIdx, usdmIn)` — slippage preview before trade
* [ ] `quoteSell(marketId, optionIdx, shares)` — slippage preview for sells
* [ ] ERC-1155 position display in portfolio (`balanceOfBatch`)
* [ ] `watchContractEvent` polling for live trade feed
* [ ] Order book panel — display resting limit orders
* [ ] Post-trade confirmation toast with shares received
* [ ] `sellToAMM()` instant sell flow

***

## Contract Addresses

```ts
// config/markets.ts
export const MARKETS_ADDRESS = process.env.NEXT_PUBLIC_MARKETS_ADDRESS as `0x${string}`;
export const PROFILES_ADDRESS = "0x9F0708145BCCD1F5B16F610cB8a75A63fA4A9a24";
export const USDM_ADDRESS = "0xFAfDdbb3FC7688494971a79cc65DCa3EF82079E7";
```

***

## Gas Settings (MegaETH)

```ts
// Near-zero gas on MegaETH — use these for all transactions
const txConfig = {
  maxFeePerGas: 1_000_000n,      // 1 gwei
  maxPriorityFeePerGas: 0n,
};
```
