pumperp executes perpetual exposure through **Avantis** on Base — the direct analogue to Fission's **Jupiter Perps** on Solana.

## Integration surface

Implementation: `backend/src/services/perp/avantis.ts`

| Concern | Source |
| --- | --- |
| Build txs | `https://tx-builder.avantisfi.com` |
| Pair metadata | `https://data.avantisfi.com/v2/trading` |
| Mark/oracle | Pyth Hermes (`hermes.pyth.network`) |
| Read positions | Data API + onchain `TradingStorage` |

## Collateral

- **USDC** on Base — LP fees arrive as USDC from Clanker FeeLocker; desk manager deploys USDC directly as Avantis collateral
- **Buybacks** (separate from desk collateral): `swapUsdcForToken` routes USDC → WETH (Uniswap v3) → creator/PUM token (Uniswap v4) — not 1inch
- Legacy WETH accumulators in `buyback-engine` may still drain old state on restart

## Min notional

```typescript
AVANTIS_MIN_NOTIONAL_USDC = 100  // collateral × leverage
AVANTIS_MAX_LEVERAGE = 75
```

Desk deploy is re-queued if `deployUsdc × leverage < min notional`.

## Onchain contracts

From `config.ts`:

| Name | Purpose |
| --- | --- |
| `AVANTIS_TRADING` | Trading entrypoint |
| `AVANTIS_TRADING_STORAGE` | Position storage reads |
| `AVANTIS_PRICE_AGGREGATOR` | Oracle aggregator |

Verify current addresses in repo `config.ts` before mainnet ops.

## Operations

```bash
npx tsx backend/scripts/avantis-test.ts read
npx tsx backend/scripts/avantis-test.ts open
npx tsx backend/scripts/avantis-test.ts close
```

Requires funded protocol wallet and valid RPC.

## `PerpVenue` interface

Workers import `avantis` — not Avantis types directly. To swap venues, implement `PerpVenue` in a new adapter; do not leak venue-specific fields into `desk-manager.ts`.

## Position model

Each enrolled token may have **one desk** referencing `(market, side, pairIndex, tradeIndex)`. This is **per-token**, not the older pooled-bucket design described in the v7 plan doc.

## PnL

Always check `PerpPosition.pnlAvailable` before profit attribution. False = price feed unavailable.