Guide and reference

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.

STEP 1 — create the agent's account
STEP 2 — give it a key that can only ask the vault
STEP 3 — delete its full-access key
This is the step that matters. Until the full-access key is gone, the agent account can still do anything. After it, the restricted key is the only way to act as that account, and nobody — the owner included — can widen it.
STEP 4 — register the policy (owner only, 1 yoctoNEAR attached)

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 reason

From 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"
      }
    }
  }
}
Give the agent the restricted key only. A function-call key can be handed to a process you do not trust. A full-access key cannot.

API reference

Agent methods

MethodWhat 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

MethodWhat 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

ReasonMeaning
vault_pausedThe owner has pulled the kill switch.
agent_disabledThis agent is switched off.
amount_zeroThe request asked for nothing.
exceeds_per_tx_capMore than a single payment is allowed to move.
exceeds_daily_capMore than is left in the agent’s rolling 24-hour window.
recipient_not_allowlistedThe recipient is not an address the owner chose.
insufficient_vault_balanceThe vault does not hold that much.
token_not_acceptedThe 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.

Live build. 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.