An agent is software that acts for the organisation without a person approving each step. A payout run for coupons and dividends is one example. Each agent acts inside a mandate that the chain enforces: the contracts and functions it may call, the most it may move of each metered asset in one transaction and in one period, and the date the mandate ends. The agent signs with a managed custody key that the platform holds, and only an organisation owner creates agents and changes their mandates. A mandate does not restrict recipients, and its ceilings meter only transfer, transferFrom and approve on the assets it lists. Agents and mandates explains what the chain refuses and how the starter mandate is set.
Each row on the list is one agent. The list opens with the newest agent first, shows 20 agents per page, and refreshes on its own while an agent reads Setting up. “Search agents” filters it. Opening a row opens the agent's page, where the owner reads the mandate and the limits used this period, replaces the mandate, manages the roles of the agent's account or revokes the agent. The foot of the list holds “Halt all agents”, the organisation's kill switch, which revokes every agent at once.
The “Agents” page before any agent exists, with “Create agent” in the header.
The page describes itself as “Agents act for your organisation inside a mandate that the chain enforces. Only owners create agents and change mandates.” With no agent, it reads “No agents yet” and “Create an agent to let software run coupon and dividend payouts within limits you set.” The “Halt all agents” control sits below. Once an agent exists, the table, searched with “Search agents”, shows “Name”, “Status”, “Account”, “Created” and “Revoked”.
Steps
Open the Create agent sheet
Select Create agent. The sheet opens with an “Agent name” field and the starter mandate the platform proposes. While the proposal loads, the mandate area shows a placeholder. Reading the proposal creates nothing.
Name the agent
Enter the Agent name, up to 120 characters. The sheet shows “Enter a name for the agent.” until you do.
Review the mandate
The mandate editor holds four settings. Change what the agent should not get, and add what it needs.
-
Expires sets the date and time the mandate ends. It must be in the future.
-
Ceiling period is the window the per-period ceilings count over. Choose “1 hour”, “1 day” or “7 days”. When you edit a mandate whose period is none of these three, the list shows its period as a fourth choice.
-
Allowed contracts and functions lists each contract the agent may call and, under it, the functions it may use there. The editor names the known functions, such as “Fund coupon payments”, “Pay a coupon to a holder”, “Declare a dividend”, “Pay a dividend to a holder”, “Approve spending of an asset” and “Transfer an asset”, each with its own add button.
To add a function the editor does not name, enter its 4-byte selector in “Function selector”, such as
0x12345678, and select “Add function”. Select “Add contract” and enter a “Contract address” to allow another contract. Every contract needs at least one function, and the Console says “Choose at least one function for this contract.” when one has none. Remove a contract with “Remove this contract”. -
Ceilings per asset lists each asset the agent may move. Select “Add asset”, enter the “Asset address”, and set the “Ceiling per transaction” and the “Ceiling per period”. Both fields take the amount in your own number format, group it when you leave the field, and accept a
k,morbsuffix such as1.5k. Every asset needs both ceilings.A ceiling limits only
transfer,transferFromandapproveon that asset. Another function the mandate allows, such as a mint or a payout call, counts against no ceiling, so allow only the functions the agent needs.
Under the editor the footer names the first thing that blocks you, such as “Set an expiry in the future.”, “Add at least one contract.” or “List each contract once.”
Confirm and create
Continue to the confirmation, which reads “Create this agent with this mandate” and summarises the “Agent name”, “Expires”, “Ceiling period”, the number of allowed contracts and the number of assets. Select Create agent and confirm with your wallet verification. The Console shows “Agent created” and opens the agent's page. A new agent reads “Setting up” until its account exists on the chain, and “Active” after that.
Open an agent
Select a row to open the agent's page. It has two tabs, Overview and “Activity log”, and a status badge beside the name.
The Overview tab shows these cards:
- Identity with “Status”, “Account”, “Signer”, “Mandate owner”, “Identity”, “Created” and, for a revoked agent, “Revoked” and “Revoked by”. “Revoked by” reads “The kill switch of this agent” or “The kill switch of the organisation”.
- Mandate with “Expires”, “Ceiling period” and “Allowed contracts and functions”. A mandate with no contract reads “The agent may not call any contract.”
- Limits this period with, for each asset, how much the agent has used of its ceiling for the period, and its “Ceiling per transaction”. When the mandate sets no asset or native ceilings, the card reads “The mandate sets no asset or native ceilings. Ceilings meter only transfers, approvals and native value. A ceiling does not meter any other call the mandate allows.” The card means nothing is metered: the agent can still make every call the mandate allows.
An active agent's header also has Manage roles when the agent has an account and your account may grant roles. It opens the roles sheet with the agent's account already chosen. A role you grant that account lets the agent call that role's functions on any contract the mandate lists, and no ceiling meters those calls.
A notice at the top of the Overview tab explains an agent that is not active: “The agent is being set up”, “Setting up the agent failed” or “This agent is revoked”. When the chain does not answer, the page says “The mandate could not be read from the chain. Try again in a moment.”
Edit a mandate
Select Edit mandate in the header of an active agent. The sheet reads “Replace the mandate of” the agent's name and “The new mandate applies as soon as the change lands on the chain.” It holds the same editor as the create sheet, filled with the current mandate. Change it, continue to the confirmation, select “Replace mandate” and confirm with your wallet verification. The Console shows “Mandate replaced”.
The new mandate replaces the old one entirely: it drops the previous allowed calls, asset rules and counters, and starts a new period count. You can replace the mandate of an active agent only.
Revoke an agent
On the “Overview” tab of an active agent, the danger row “Revoke agent” ends the agent's mandate for good. Select Revoke agent, enter the “Reason”, and confirm with your wallet verification, or select “Keep agent” to stop. The sheet says the agent stops at once, and that revoking is final: the agent can never act again, and the only way to grant new limits is to create a new agent. The Console shows the agent's name followed by “revoked”, and the agent reads “Revoked”.
Halt all agents
Halting is not a pause. The halt revokes every agent of the organisation that is not already revoked, and cancels each agent's transactions that are still waiting in the queue. An agent the halt revokes stays revoked after you turn the halt off, so you create each agent again with a new mandate.
To halt, select the danger row Halt all agents below the list, enter the “Reason”, and confirm with your wallet verification, or select “Keep agents running” to stop.
While the halt is on, a banner reads “All agents are halted”, with your reason and “Halted on” followed by the date, and the danger row shows “Turn off halt” instead. Select Turn off halt, enter the “Reason”, and confirm, or select “Keep halt on” to stop. Turning the halt off lets the organisation create agents again.
Agent statuses
Troubleshooting
“Create agent” is unavailable
All agents are halted, and the page says “Turn off the halt to create agents.” Select Turn off halt and confirm.
Through the Platform API, a creation while the halt is on fails with DALP-199552.
The sheet does not continue
The footer names the first problem with the mandate or the name. The Console stops an empty contract list, a contract
without a function and an asset without both ceilings. Through the Platform API, DALP-199554 refuses an expiry that
is not in the future, a contract, asset or function listed twice, a transfer, transferFrom or approve on a
contract that has no asset ceiling, and any other function on an asset that has one. data.rule names the rule. This
is a caller error, and sending the same mandate fails again.
An agent stays on “Setting up”
The agent's account is still being created on the chain, and the page updates by itself. If the agent then reads Failed, it never became active. Create a new agent with the same mandate.
The mandate could not be read from the chain
The agent is active but the chain read did not answer. Reload the page in a moment. The mandate and the limits show again once the read succeeds.
“Edit mandate” or “Manage roles” is missing
Both show only on an active agent. A revoked agent, an agent that is still being set up and a failed agent have no
header actions, and the platform refuses a change to them with DALP-199553. Manage roles also needs an account
on the agent and your permission to grant roles.
“Agents” is missing from the sidebar
Only an organisation owner opens the page, and the platform refuses every agent route for anyone else with
DALP-199555. Ask an owner to make the change.
API routes
The Platform API serves the same actions under /api/v2/agents, and every route is owner only. GET /api/ lists the agents and POST /api/ creates one. GET /api/ returns the starter mandate the sheet starts from. GET /api/ reads one agent with its mandate and usage, PUT /api/ replaces the mandate, and POST /api/ revokes the agent. GET /api/ reads the halt and PUT /api/ turns it on or off. See the API reference for the schemas.