Docs

The Orrery developer guide.

With Orrery, an agent's signer may spend from its operator's smart account, but only inside caps anyone can read. A merchant who is paid can read the paying address on chain for free, or buy a signed reading that also includes a fresh probe of the agent's endpoints.

Add the SDK

pnpm add @orrery-tech/sdk viem

Operators: plot an agent's orbit

From your wallet, the Agents section of the dashboard handles every step. It deploys the account (a Safe running the Safe7579 adapter and the Orrery policy module), registers an ERC-8004 identity for the agent, generates the signer, opens a session with the caps you choose, and hands you the signer's key file for the agent.

Prefer a script? The agent generates a new signer and signs its consent, then the operator submits the session from its own account. Each signer serves one session only.

import { signSessionConsent, operatorCalls, type Policy } from "@orrery-tech/sdk";
import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(generatePrivateKey()); // kept by the agent
const policy: Policy = {
  caps: [{ token: USDG, perTx: 10_000_000n, perDay: 50_000_000n, floatMax: 20_000_000n }],
  targets: [],
  validUntil: BigInt(Math.floor(Date.now() / 1000) + 30 * 86400),
  increaseDelay: 3600,
};
const consent = await signSessionConsent(signer, { chainId, module, account, agentId, policy });
const data = operatorCalls.openSession(agentId, signer.address, policy, consent);
// submit `data` to the module from your account (Safe execTransaction)

Agents: pay over x402

Load the dashboard's key file into the agent's environment. Payments leave from the float, and ahead of each one the SDK refills the float through the module, never past the caps.

import { agentFromEnv } from "@orrery-tech/sdk";

const agent = agentFromEnv(); // loads ORRERY_SIGNER_KEY and the other key file values
const res = await agent.x402Fetch("https://api.example.com/data");

Merchants: take a reading of the payer

A single wallet signature under Credits in the dashboard gives you an API key. One call then fetches the signed reading and verifies it against the chain.

import { checkPayment } from "@orrery-tech/sdk";

const v = await checkPayment(payer, process.env.ORRERY_API_KEY);
if (v.ok) {
  // v.result.caps, v.result.status, v.result.endpointsLive, v.result.validUntil
}

Or call it over plain HTTP from whatever language you use:

curl -H "authorization: Bearer $ORRERY_API_KEY" \
  https://api.orreryagent.com/v1/check/by-signer/0xPAYING_ADDRESS

Fields in a signed reading

signer, account, agentIdThe subject of the reading. What it states applies to payments sent by this signer.
status0 none · 1 active · 2 paused · 3 revoked · 4 expired.
capsFor each token: the per payment cap, the daily cap, the float ceiling and today's spend.
targetsHashA hash over the allowed calls, which the JSON also lists in full.
validForThe first moment at which the module would let this signer's caps go up.
accountKind, otherAccountModulesWhether the account is a recognised Safe, and whether anything else holds access to it.
verified, endpointsLive, registrationValid, domainVerifiedVerification status, plus the most recent probe of the agent's registration and endpoints.
issuedAt, validUntilWhen the reading was signed, and the time it stays valid until.

Scope: the caps count what this signer moves out of the account, in the listed tokens and in native ETH.