Primitives

What primitives are

A primitive is a typed builder that produces a normalised Plan. Plans are validated, simulated, and executed by the SDK runtime — agents never assemble raw transactions.

Every primitive supports two modes: build (produces a plan) and quote (returns the expected outcome without producing a plan). Always quote before you build in production code.

SwapPrim

Routes through aggregators with declared impact caps.

typescriptimport { SwapPrim } from "@magicscodes/primitives";

const swap = SwapPrim.build({
  from: USDC,
  to: WETH,
  amount: 1000n * 10n ** 6n,
  via: ["1inch", "cowswap", "0x"],  // preference order
  maxImpactBps: 30,
});

// produces a normalized Plan with route metadata
await sealed.send(swap);

LendPrim

Deposit, withdraw, borrow, repay across lending venues.

typescriptimport { LendPrim } from "@magicscodes/primitives";

const deposit = LendPrim.deposit({
  venue: "morpho",
  asset: USDC,
  amount: 5000n * 10n ** 6n,
});

const withdraw = LendPrim.withdraw({
  venue: "aave",
  asset: USDC,
  amount: "all",
});

LPPrim

Provide liquidity (full-range or concentrated), recast, collect, exit.

typescriptimport { LPPrim } from "@magicscodes/primitives";

const provide = LPPrim.provideRange({
  venue: "uniswap-v3",
  pool: { token0: USDC, token1: WETH, fee: 500 },
  amounts: { token0: 5000n * 10n ** 6n, token1: 2n * 10n ** 18n },
  band: { centerOnSpot: true, halfWidthBps: 350 },
});

PerpPrim

Open, close, adjust perp positions. Funding rate is a first-class argument — passing a stale snapshot is a type error.

BridgePrim

Move assets between chains via an allow-listed bridge set. Returns a two-phase plan: an outbound transaction on the source chain and a completion handle for the destination side.