Put your own agent on an allowance.
Design a policy, get the exact commands to deploy it, and connect an agent. Everything on this page runs against NEAR testnet with free faucet funds.
1 · Design a policy
A policy belongs to one agent and one asset. Fill it in and the commands in step 3 update as you type.
2 · Test a request against it
Evaluated in your browser, in the same order the contract checks. Nothing is sent. To see the real contract decide, use the attack console.
3 · Deploy it
Four steps with near-cli-rs.
The vault contract must already be deployed to the vault account —
scripts/reproduce-demo.sh does that and everything below in one run.
4 · Connect an agent
The agent needs two things: the vault's account id and its own restricted key. It asks; the vault decides. A refusal returns a reason instead of failing, so the agent can report why rather than retry blindly.
From Python
The client in this repository signs with the standard library — nothing to install.
import os
import nearlite as near # scripts/nearlite.py — standard library only
key = near.Key(os.environ["AGENT_KEY"])
tx_hash, result = near.send(key, "bot.my-vault.testnet", "my-vault.testnet", [
near.function_call("request_spend", {
"recipient": "payee.my-vault.testnet",
"amount": "5000000000000000000000", # yoctoNEAR
"memo": "monthly API credits",
})
])
print(near.events(result)) # spend_allowed, or spend_denied with a reasonFrom any MCP-capable agent
scripts/mcp_server.py exposes the vault as two tools,
request_payment and get_policy. The model can call them as
often as it likes; the limits are enforced on-chain, not by the model.
{
"mcpServers": {
"agent-allowance": {
"command": "python3",
"args": ["/path/to/Agent_Allowance/scripts/mcp_server.py"],
"env": {
"AGENT_ACCOUNT": "bot.my-vault.testnet",
"AGENT_KEY": "ed25519:…",
"VAULT_ACCOUNT": "my-vault.testnet"
}
}
}
}API reference
Agent methods
| Method | What it does |
|---|---|
request_spend(recipient, amount, memo) | Ask to pay native NEAR. Returns {allowed, reason}; schedules a transfer only when allowed. |
request_spend_ft(token_id, recipient, amount, memo) | The same, for an NEP-141 token the owner has opted in. |
Owner methods — each requires 1 yoctoNEAR
| Method | What it does |
|---|---|
add_agent(agent_id, per_tx_cap, daily_cap, allowlist) | Register an agent with a native-NEAR policy. |
update_policy(agent_id, per_tx_cap, daily_cap, allowlist) | Replace an agent's native-NEAR policy. |
set_agent_enabled(agent_id, enabled) | Switch one agent off or on. |
revoke_agent(agent_id) | Remove an agent entirely. |
set_paused(paused) | The kill switch: pause or resume every agent. |
add_token(token_id) · remove_token(token_id) | Start or stop accepting an NEP-141 token. |
set_ft_policy(agent_id, token_id, per_tx_cap, daily_cap, allowlist) | Give an agent a policy for one token. |
revoke_ft_policy(agent_id, token_id) | Remove that token policy. |
withdraw(amount, to) · withdraw_ft(token_id, amount, to) | Take funds back out of the vault. |
Views
dashboard returns the whole state in one call. Also:
get_owner · is_paused · get_policy ·
get_agent_status · list_agents · vault_balance ·
available_balance · stats · get_ft_policy ·
ft_balance · list_tokens
Why a request is denied
| Reason | Meaning |
|---|---|
vault_paused | The owner has pulled the kill switch. |
agent_disabled | This agent is switched off. |
amount_zero | The request asked for nothing. |
exceeds_per_tx_cap | More than a single payment is allowed to move. |
exceeds_daily_cap | More than is left in the agent’s rolling 24-hour window. |
recipient_not_allowlisted | The recipient is not an address the owner chose. |
insufficient_vault_balance | The vault does not hold that much. |
token_not_accepted | The owner has not opted this token in. |
Checks run in that order, and the first failure decides. Every
decision is emitted as a NEP-297 event — spend_allowed,
spend_denied, ft_spend_allowed, ft_spend_denied
— under the standard name agent_allowance.
withdraw_ft is in the contract and
covered by tests, but landed after the build currently deployed at
agent-allowance.testnet. It reaches the live vault on the next deploy.What it does not solve
- A permitted but foolish payment. If the agent may send 1 NEAR to an allowlisted address, a tricked agent can still send it. The cap bounds the loss.
- A stolen owner key. The owner's full-access key controls the policy. That is a different threat model.
- Prompt injection itself. It still works. It just achieves little.
- Dollar limits on volatile assets. Caps are in the token's own units; there is no price oracle.
- Unregistered token recipients. NEP-141 needs storage registration; a transfer to an unregistered account fails and the balance is credited back.
- An exhausted agent key. The key's gas allowance is finite and nothing on the account can refill it. The funds are safe in the vault; the agent identity is replaced.
- An audit. This is an unaudited testnet build. Do not put real funds behind it without review.