THE TOME · v0.1

The grimoire, indexed.

Welcome, apprentice. This is the working reference for magics — a place to learn the rituals, inspect the primitives, and inscribe your own agents.

Welcome

magics is an agentic protocol on Base. It lets you summon autonomous agents — small, audited programs — that execute DeFi strategies on your behalf, within bounds you set, without ever taking custody of your keys.

The Tome is the prose half of that system. The runtime is the rest. Together they make a quiet workshop: you set intent, the order works.

Live on Base

The three core contracts are deployed and verified on Base mainnet (chain id 8453). Bytecode matches the source at the tagged commit in the contracts repo.

SealVault at 0xF4a7591B10398B7b5dBB0FedBC52c7F7B7cFCacB
AgentRegistry at 0xc6967a98Ac4f0bf9B918B6c1e0E5B868d948E99f
MagicsRouter at 0xdD7b9C84aee89c6620011e6f34a0d3aAE45F032F

What lives in the Tome

Five sections, ordered from gentlest to deepest:

Foundations — installation, your first cast, a glossary you can keep open.
Concepts — the four primitives the entire protocol composes from. Read these once, internalise them, and the rest of the surface stops feeling foreign.
The Grimoire — every shipped agent, what it does, its trade-offs, and the venues it touches.
Inscription — the SDK, primitive set, and patterns for composing your own agents from the catalog of building blocks.
Reference — exhaustive lookup. API surface, contract addresses, event signatures, error codes.

Quick paths

Pick the door that matches your mood.

Quickstart8 minutes

Connect a wallet, summon your first agent, and watch the first cast settle.

ConceptsRead deeply

Intents, agents, seals, mana — the four primitives the protocol orbits.

Inscribe your ownBuilder track

Compose new agents from the primitive set. TypeScript, Solidity, audited templates.

ReferenceLookup

Mainnet addresses, every external function, every event. Bookmark this one.

Source

Everything magics ships in the open lives under the magics-codes GitHub organisation. Three repositories:

magics-contract — the Foundry project. Three contracts, four interfaces, the reference strategy, and the test suite that produces the 17/17 passing baseline.
magics-cli — the local CLI, on npm as @magicscodes/cli. Mint and revoke flows never touch the root signer; only ephemeral session keys.
docs — the plain-markdown source for the longer-form writeups. The pages you are reading here mirror selected entries from that repo, with the authoritative copy living on GitHub.

Updates land on @magicsdotcodes. Security reports go to security@magics.codes.

Three principles

Everything in the Tome was written with three commitments in mind. If a feature or page violates them, file an issue — it is a bug.

Custody is sacred. Agents never hold your keys. They act through scoped, revocable session seals. Every page that describes an agent must describe its seal surface.
Honesty over polish. If a strategy can lose money, the docs say so, near the top, in plain prose. If a metric is a projection, it is labelled.
Composition over magic. Every shipped agent is built from the same primitives you have in the SDK. There is no private surface. What we built, you can build.

Welcome

The Tome is the prose half of that system. The runtime is the rest. Together they make a quiet workshop: you set intent, the order works.

Live on Base

The three core contracts are deployed and verified on Base mainnet (chain id 8453). Bytecode matches the source at the tagged commit in the contracts repo.

What lives in the Tome

Five sections, ordered from gentlest to deepest:

Foundations — installation, your first cast, a glossary you can keep open.

Concepts — the four primitives the entire protocol composes from. Read these once, internalise them, and the rest of the surface stops feeling foreign.

The Grimoire — every shipped agent, what it does, its trade-offs, and the venues it touches.

Inscription — the SDK, primitive set, and patterns for composing your own agents from the catalog of building blocks.

Reference — exhaustive lookup. API surface, contract addresses, event signatures, error codes.

Source

Everything magics ships in the open lives under the magics-codes GitHub organisation. Three repositories:

magics-contract — the Foundry project. Three contracts, four interfaces, the reference strategy, and the test suite that produces the 17/17 passing baseline.

magics-cli — the local CLI, on npm as @magicscodes/cli. Mint and revoke flows never touch the root signer; only ephemeral session keys.

docs — the plain-markdown source for the longer-form writeups. The pages you are reading here mirror selected entries from that repo, with the authoritative copy living on GitHub.

Updates land on @magicsdotcodes. Security reports go to security@magics.codes.

Three principles

Everything in the Tome was written with three commitments in mind. If a feature or page violates them, file an issue — it is a bug.

Custody is sacred. Agents never hold your keys. They act through scoped, revocable session seals. Every page that describes an agent must describe its seal surface.

Honesty over polish. If a strategy can lose money, the docs say so, near the top, in plain prose. If a metric is a projection, it is labelled.

Composition over magic. Every shipped agent is built from the same primitives you have in the SDK. There is no private surface. What we built, you can build.