How it works

A three-minute read: what you set up, what the owner signs, what you can build, and what is checked before an agent moves funds.

Set up in three steps

Get a partner API key

Create one in the Partner Dashboard. It lives on your backend, as NEAR_INTENTS_AGENT_API_KEY, and works for all of your agents. See Partner API Key.

The owner signs twice

Your backend generates two requests and the owner’s wallet signs each one: agent_create sets the agent’s rules (its policy), and grant_issue gives your backend a grant token. See Owner Signing.

Your backend acts

Call swap, transfer, withdraw and the other actions with the key and the grant token. The owner doesn’t sign these, and every one is checked against the policy.

What you can build

You’re building	Actions it uses	Policy rules to set
A trading assistant	`swap`, with `dry: true` quotes	`assets`, per-asset `limits`, a daily USD `budget`, a `schedule` for trading hours
A payout or payroll bot	`transfer`, `withdraw`	`destinations` set to `only` the payees, a `timelock_ms` so the owner can review and cancel, a monthly `budget`
A private treasury agent	`shield`, `unshield`, confidential `swap` and `withdraw`	`confidential: true`, and `owner_approval` for a vote on every payment
An agent that also acts outside NEAR Intents	`native/near/…`, `native/evm/…`, `native/solana/…`	`native` with only the methods it needs: NEP-413 message signing for listed services, NEAR transfers and calls, EVM typed data under listed domains, EVM and Solana signatures. See Native Accounts.
Funding from any chain	`deposit`	None. Deposits need no grant and no action in the policy; only a frozen agent refuses them. See Funding.

Every row is one agent with one policy. Run as many assistants or bots against it as you like, each with its own grant.

The pieces

Piece	What it is
Owner	The person who controls the agent with a NEAR account or a passkey. EVM wallets work only where enabled. Only the owner’s signature can change the agent’s rules, issue or revoke grants, freeze or delete it.
Agent	One agent account: its own wallet on NEAR Intents, its own policy and its own USD budget. One owner can have many agents.
Partner API key	`naa_…`. Identifies your backend and one partner’s agents. Never moves funds by itself.
Policy	What is allowed. One owner-signed rulebook for the whole agent: actions, assets, limits, destinations, budget, timelock, schedule, owner approval, confidential access and freeze.
Grant	Who may act. One grant token (`ngt_…`) that the owner signed for, with a label and an expiry. A grant carries no permissions of its own.
Budget	A USD spending cap in the policy, counted across all assets. Shared by every grant.
Timelock	A delay in the policy. Every money action waits before it runs, and the owner can cancel it while it waits.
Schedule	Weekly time windows in the policy that say when money actions may run.
Approval	An optional policy setting. Every money action waits for the owner’s vote.
Freeze	The owner’s emergency stop. A frozen agent refuses every action, deposits included, until the owner unfreezes it.
Confidential	The agent’s private balance on Confidential Intents. The policy turns it on.

Policy decides what. Grant decides who. An agent has one policy and many grants. The policy and the USD budget belong to the agent, so every grant follows them and shares one budget. Changing a rule never means issuing new grants, and issuing or revoking a grant never changes a rule.

Three credentials

Each call uses one or more of these. None of them can replace another.

Partner API key

naa_…, sent as X-API-Key. Kept on your backend. Says which partner is calling. One key works for all of your agents.

Grant token

ngt_…, sent as X-Grant-Token. Created and kept by your backend. Says which owner-signed grant an action runs under.

Owner signature

Made by the owner’s wallet. Proves the owner agrees to an action, such as creating the agent, changing the policy or giving a grant.

Never put the partner API key or a grant token in a browser, a mobile app or an AI model’s prompt.

Agents

An agent is one account with its own assets and its own rules. Each agent has:

One owner. A NEAR account or a passkey. EVM wallets work only where enabled: GET /v1/network lists the owner types you can use in supported_owner_types, and EVM isn’t enabled by default. One owner can have many agents.
One wallet with its own NEAR Intents account, holding a public balance and a confidential balance. Agents never share balances or history.
One policy. The rules the owner signed.
One USD budget, part of the policy and shared by every grant on the agent.

NEAR owners use their own NEAR account. Passkey and EVM owners don’t need one: the API derives a NEAR account for them from their public key, and that account controls the agent’s wallet rules on-chain. See Owner Accounts.

Agent status	Meaning
`PENDING`	Created. Waiting for the owner’s first signature to confirm.
`ACTIVE`	Ready for grants and actions
`ARCHIVED`	Hidden by the owner. Funds stay in the wallet, and the owner can restore it.
`DELETED`	Deleted by the owner
`ABANDONED`	The owner never signed, so the agent never started

Lifecycle

Create

Your backend calls generate-intent with type: "agent_create", a name, the owner’s public identity and the complete first policy. The API returns one request for the owner to sign. The agent is PENDING.

Owner signs the rules (signature 1)

This signature links the agent to the owner and installs the policy. The API pays the gas. The agent becomes ACTIVE once the policy is confirmed on-chain and the wallet reads it back.

Owner grants access (signature 2)

Your backend creates a grant token and sends only its fingerprint. The owner signs a grant_issue with a label and an expiry. The grant names who may act and until when. What that grantee may do is the policy. After this, actions need no owner signature. Each extra grant is one more signature.

Your backend acts

Your backend calls swap, withdraw, transfer, shield, unshield and the other actions with your partner API key and the grant token. The owner doesn’t sign these.

Owner manages

Changing the policy, freezing or unfreezing, revoking a grant, cancelling a queued action, archiving and deleting each take one owner signature.

Owners can’t change their key, and lost wallets can’t be recovered. If the owner loses access to their wallet, nobody can change the agent’s rules, issue new grants or delete it, including you and the Agent API.

Two kinds of requests

Owner intents
Agent actions

For anything the owner must agree to. Every owner intent uses the same four calls:

POST /v1/generate-intent: get the exact payload the owner must sign, plus a readable preview.
The owner’s wallet signs intent.payload unchanged.
POST /v1/submit-intent: send the wallet’s output back.
GET /v1/status?correlation_id=…&wait_ms=30000: wait for the result.

Types: agent_create, policy_update, agent_freeze, agent_unfreeze, grant_issue, grant_revoke, execution_cancel, agent_archive, agent_restore, agent_delete, approval_vote. See the full list.

For moving funds. Your backend calls these directly, with a grant token. Each action has its own endpoint under /v1/agents/{agent_id}/:swap, withdraw, transfer, shield, unshield and recover. swap and withdraw also take dry: true to return a quote without running. The spending rules never refuse a quote. It adds spend, fee and warnings, and each rule the live call would fail comes back as a warning under that call’s error code. The native/… routes use the agent’s own NEAR, EVM and Solana keys outside NEAR Intents. They need a grant too, and each one is off until the policy’s native block switches it on. See Native Accounts.Each call needs an Idempotency-Key (except a dry quote) and returns a correlation_id that starts with op_. Track it with GET /v1/status.deposit is the exception: it needs no grant. See Deposits.

The policy

The policy is what the agent may do. The owner signs the complete policy when creating the agent and again for every change. It has these parts:

Field	What it controls
`actions`	Which of `swap`, `transfer` and `withdraw` are allowed. Deposits need no action (a frozen agent refuses them too), and deleting the agent is the owner’s own intent.
`assets`	`"any"`, or the exact `asset_id`s the agent may spend. A swap may still buy an unlisted one.
`limits`	Per-asset caps in atomic units: `per_transaction`, `hourly`, `daily`, `monthly`.
`max_actions_per_hour`	A cap on the number of money actions, or `null`.
`destinations`	Where `withdraw` and `transfer` may send funds, for every grant. `only` allows exactly the listed entries, `except` blocks them, `any` allows everything. `destinations` is required in the `agent_create` policy. `only` with an empty list allows no destination, so nothing leaves the agent until the owner lists one.
`budget`	`daily_usd`, `weekly_usd`, `monthly_usd`: USD caps per day, week and month, across every asset. Each cap’s periods start when an applied policy turns it on: 24 hours, 7 days, or the same date and time each month in UTC, clamped to the last day of shorter months. `null` means uncapped.
`timelock_ms`	How long every money action waits before it runs, from `0` up to 30 days.
`schedule`	Optional weekly windows, in an IANA time zone, in which money actions may run (`only`) or are paused (`except`).
`owner_approval`	When `true`, every money action waits for the owner’s vote. NEAR, EVM and passkey owners can all vote.
`confidential`	When `true`, allows `shield`, `unshield` and the confidential form of every allowed action.
`frozen`	When `true`, the agent refuses every action, new deposit addresses included.
`native`	Optional. Switches on the agent’s own NEAR, EVM and Solana keys outside NEAR Intents, one method at a time. Omitted, every method is off. See Native Accounts.

The timelock, the schedule and the budget cover money actions: swaps, withdrawals and transfers. They don’t apply to deposits. The budget doesn’t count shield and unshield either. Native requests skip all three, and destinations and owner_approval too. Each budget cap’s periods start when the applied policy turns it on, so a daily cap turned on at 05:00 resets in full at 05:00 each day. resets_at says when. Moving funds to your own account on another chain or venue, such as your Hyperliquid or Polymarket address, counts like any withdrawal. A deposit back does not credit it. Two layers enforce the policy. The Agent API enforces destinations, budget, timelock_ms and schedule, and counts the per-asset limits and max_actions_per_hour before anything reaches the wallet. The agent’s wallet enforces the rest. Neither layer overrides the other, and none adds allowance to another: a bigger USD budget never lifts a per-asset limit. Changing the policy is one owner signature over the complete policy. Changes to only destinations, budget, timelock_ms or schedule apply at once, with no transaction. Other changes are written on-chain, and actions wait with policy_not_ready until the wallet reads them back. Policy changes have a 10-minute cooldown, except a freeze. An unfreeze has its own 10-minute cooldown (agent_unfreeze_throttled). See Policies & Limits for each setting in detail.

Grants

A grant says who may act for the agent: one grant token, until it expires or is revoked. It carries no permissions of its own. Everything the grantee may do comes from the agent’s policy. Your backend creates the token and the owner signs only its SHA-256 fingerprint, with a label and an expiry of at most 365 days. Create one grant per user session, assistant or bot: an agent holds up to 50, and revoking one never touches another. All grants share the agent’s one policy and one USD budget. See Grants. Owner-only powers can’t be delegated. A grant can run money actions, but only the owner’s signature changes the policy, issues or revokes grants, freezes, archives or deletes the agent.

The checks every action passes

Before an action runs, it passes these checks in order. Each check stands on its own: only a change to the layer that refused it lifts the refusal. An agent action passes five checks in order: grant, policy rules (action, destination and schedule), timelock, USD budget and wallet policy, then runs on NEAR Intents. A failed check stops it with agent_grant_required, policy_action_denied, policy_destination_denied, policy_schedule_denied, spend_budget_exceeded or policy_denied.

Grant

Is there a live grant for this agent? A missing, expired, revoked or unknown token returns agent_grant_required.

Policy rules

Is the action turned on, is the destination allowed and is the schedule open? If not: policy_action_denied, policy_destination_denied or policy_schedule_denied.

Timelock

If the policy sets timelock_ms, the action waits as QUEUED and the owner can cancel it. When it’s released, the schedule is checked again.

USD budget

Is there room left in the daily, weekly and monthly caps? If not: spend_budget_exceeded. This is decided when the action dispatches, so a queued action counts when it runs, not when it was queued.

Wallet policy

The API counts the asset’s hourly, daily and monthly limits and the hourly action cap when the action dispatches, shield and unshield included. If one is used up: policy_limit_exceeded or policy_action_limit_exceeded. The agent’s wallet then checks the asset and its limits again. If its rules refuse: policy_denied. If the owner turned on approval, the action waits as PENDING_APPROVAL until the vote.

Two conditions apply before any of these, to every action:

policy_not_ready (409): the latest policy revision isn’t APPLIED yet.
wallet_frozen (409): the owner froze the agent. Only an agent_unfreeze intent resumes it.

A swap quote or withdrawal preview (dry: true) is never refused by the account’s rules (action, destination, assets, schedule, USD budget, per-asset limits) or by the balance (insufficient_balance). Each one the live request would fail comes back in warnings under the code that request would get, so you can see a refusal coming. An asset GET /v1/tokens does not list (unsupported_token) or an invalid recipient (invalid_address) refuses the quote itself with 400, before any provider call. A quote without such a warning is a snapshot, not a guarantee: other work can use the budget first. An archived, deleted or frozen account gets no quote: it is refused with the code the live request gets (agent_archived, agent_deleted, wallet_frozen). Only one money action runs per agent wallet at a time. An overlapping request is refused with wallet_busy before anything is sent. Retry it with a new Idempotency-Key once the first one finishes. Fix the layer that refused: every error names it in layer. Ask the owner to change the policy for policy and budget refusals, fund the agent or send less for balance, and fix the request for request. For agent_grant_required, check the token or issue a new grant. A provider refusal with meta.retryable is worth the same key again later. A budget or limit refusal on an execution that runs now leaves no operation and charges nothing; a timelocked one released over budget ends FAILED. See Status & Errors for how to read results.

Deposits

POST /v1/agents/{agent_id}/deposit returns a NEAR Intents 1Click deposit address that credits the agent from another chain. It needs only your partner API key and an Idempotency-Key: no grant and no owner signature. A failed or late deposit refunds to the agent’s own balance. See Funding.

Gas

Some owner requests are written to the NEAR blockchain, so the agent’s wallet can enforce them on-chain. Each one is a NEAR transaction that needs gas and a small storage deposit. The Agent API pays for both. Neither you nor the owner needs NEAR for gas.

Owner request	What it writes on-chain
`agent_create`	Registers the agent’s wallet with its owner and installs the first policy. For EVM and passkey owners, it also sets up the owner’s NEAR account.
`policy_update` that changes wallet rules	Installs the new rules. Changes to only `destinations`, `budget`, `timelock_ms` or `schedule` need no transaction.
`agent_freeze` / `agent_unfreeze`	Stops or resumes the agent’s wallet
`agent_delete`	The owner’s one signature is relayed as the wallet’s `delete_wallet_policy`, which removes the policy record. Its storage deposit refunds to the sponsor, and the result’s `details.policy_record` reports the outcome.

Everything else the owner signs (grants, revoking, cancelling, archiving and approval votes) needs no blockchain transaction and no gas. Agent actions run inside NEAR Intents, which needs no gas, so you never fund an agent with gas. If the service can’t pay gas for a moment, sponsor_balance_insufficient or sponsor_busy (both 503) come back. The owner’s request stays signable, so retry the same request shortly.

Policy changes have a per-agent cooldown, 5 minutes by default. A freeze skips it, so the owner can always stop an agent in an emergency. An unfreeze has its own cooldown (agent_unfreeze_throttled).

Agent API

Quickstart

Guides

Trust & Verification

API Reference

Set up in three steps

What you can build

The pieces

Three credentials

Partner API key

Grant token

Owner signature

Agents

Lifecycle

Two kinds of requests

The policy

Grants

The checks every action passes

Deposits

Gas

Next steps

Quickstart

Policies & Limits

​Set up in three steps

​What you can build

​The pieces

​Three credentials

Partner API key

Grant token

Owner signature

​Agents

​Lifecycle

​Two kinds of requests

​The policy

​Grants

​The checks every action passes

​Deposits

​Gas

​Next steps

Quickstart

Policies & Limits

Set up in three steps

What you can build

The pieces

Three credentials

Agents

Lifecycle

Two kinds of requests

The policy

Grants

The checks every action passes

Deposits

Gas

Next steps