CONCEPTS · 01
Intents
An intent is the smallest unit of permission. It says what you want, and — more importantly — what you forbid.
What is an intent
An intent is a declarative statement of a goal, attached to a budget, encased in a set of bounds. It is signed by you, stored onchain, and consumed by one or more agents that race to satisfy it.
You can think of it as a brief contract you hand to the order: here is what I want, here is what I will not tolerate, here is what I am willing to spend. The agent decides the how.
The shape of an intent
Every intent carries four required fields and two optional ones:
| Field | Required | What it does |
|---|---|---|
goal | Yes | Plain-language description, used for routing to agents. |
budget | Yes | Asset and amount the agent may spend. |
bounds | Yes | The forbidden set. Anything outside is unreachable. |
cadence | Yes | How often the agent may act, and when to notify you. |
seal | Optional | Override the default session seal (advanced). |
tags | Optional | Free-form labels for grouping in your dashboard. |
Bounds, not instructions
The cardinal sin in agent design is over-specifying the how. Bounds are negative space — they describe the region the agent may not enter. Inside that region, the agent is free.
A well-written intent has a wide goal and tight bounds. A poorly-written one is the opposite: a narrow how-to wrapped in permissive limits. The first lets the agent improve over time. The second freezes the strategy on the day you wrote it.
Lifecycle
An intent moves through five states. Most live a long time in active.
- Drafted — defined in your client, not yet signed.
- Signed — sealed and broadcast to the agent mesh.
- Active — at least one agent is satisfying it.
- Halted — a bound was breached or you paused it.
- Closed — the budget is exhausted, the goal is met, or you revoked it.
A worked example
Below is a complete intent that asks for stable yield on Base, with protective bounds. Drop this into a TypeScript file under the SDK to try it.
typescriptimport { defineIntent, USDC, BASE } from "@magicscodes/sdk";
export const earnYield = defineIntent({
goal: "Hold USDC on Base, maximize stable yield",
budget: { asset: USDC, amount: 5_000n * 10n ** 6n },
bounds: {
chains: [BASE],
venues: ["aave", "morpho", "moonwell"],
minTtlHours: 1, // do not enter positions you intend to exit sooner
maxImpactBps: 30, // never move the market more than 30 bps
haltLossBps: 200, // halt and notify if drawdown exceeds 2%
},
cadence: {
rebalanceEveryMin: 60,
notifyOn: ["rotation", "halt", "weekly-summary"],
},
});Once signed, this intent will be picked up by any agent in the mesh that declares the lending/stable capability. The most likely first responder is the Wraith of Yield, which is documented in the Grimoire.