Executions

An execution is an action the agent runs by itself: swap, withdraw, transfer, shield or unshield. Your backend sends it with your partner API key and a grant token. The owner doesn’t sign it: the agent’s policy decides whether it may run.

At a glance

Headers: X-API-Key, X-Grant-Token and an Idempotency-Key on every execution and withdrawal preview. A swap quote (dry: true) needs only the API key.
Response: 202 with a status and a correlation_id (op_…). Follow it with GET /v1/status until it’s final.
Checks: grant, policy, schedule, policy revision, USD budget, the wallet provider’s rules, then the wallet. A refusal names the layer that blocked it.
Retries: same key and same body. A new key is new work.

Run one action

Every snippet on this page assumes this setup:

import { createAgentApi } from "@near-intents-agent-api/sdk";

const api = createAgentApi({ apiKey: process.env.NEAR_INTENTS_AGENT_API_KEY! });
// One client per grant. It sends X-Grant-Token on the calls that need it.
const assistant = api.forGrant(process.env.GRANT_TOKEN!);
const agentId = process.env.AGENT_ID!;

Send the action, then wait for its final status:

const swap = await assistant.swap(agentId, {
  origin_asset: "nep141:wrap.near",
  destination_asset: "nep141:usdt.tether-token.near",
  amount: "1000000000000000000000000", // 1 wNEAR
});

const status = await api.getStatus(swap.correlation_id, { waitMs: 30_000 });
console.log(status.status, status.failure_code); // SUCCESS, or a code that names what to fix

Store swap.idempotencyKey with your record so a retry after a crash reuses it. See Idempotency.

The actions

Action	Endpoint	Policy must allow	Counts against the USD budget
Swap	`POST /v1/agents/{agent_id}/swap`	`swap`	Yes, the input amount
Withdraw	`POST /v1/agents/{agent_id}/withdraw`	`withdraw` and the destination	Yes
Transfer	`POST /v1/agents/{agent_id}/transfer`	`transfer` and the destination	Yes
Shield	`POST /v1/agents/{agent_id}/shield`	`confidential: true`	No
Unshield	`POST /v1/agents/{agent_id}/unshield`	`confidential: true`	No
Recover	`POST /v1/agents/{agent_id}/recover`	The original action	See Recover

All five actions need a grant and an Idempotency-Key, and respect the timelock, the schedule and owner_approval. swap, withdraw and transfer also need assets in the policy that include the asset, and respect per-asset limits and max_actions_per_hour. A confidential: true request also needs confidential: true in the policy and never falls back to a public route. Amounts are atomic-unit strings. Assets are asset_id values from GET /v1/tokens. Every amount that moves funds (swap, withdraw, transfer, shield, unshield) must be greater than zero, or the request fails with validation_failed. A recipient that is not a valid address for its chain is refused with invalid_address (400) before the policy is read.

Swap

Field	Description
`origin_asset`	The `asset_id` to sell
`destination_asset`	The `asset_id` to buy. It must differ from `origin_asset` (`validation_failed`).
`amount`	The exact input amount, in atomic units of `origin_asset`. Must be greater than zero.
`min_amount_out`	Optional. The minimum output, in atomic units of `destination_asset`, sent to the provider. The quote does not apply it: a swap the provider reports below it never reads `SUCCESS` but `NEEDS_REVIEW` with `amount_out_below_minimum`.
`confidential`	Optional. Settle on the confidential balance. Default `false`.
`dry`	Optional. `true` returns a quote and runs nothing.

curl -X POST "$NEAR_INTENTS_AGENT_API_URL/v1/agents/$AGENT_ID/swap" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY" \
  -H "X-Grant-Token: $GRANT_TOKEN" \
  -H "Idempotency-Key: swap-user-123-1" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_asset": "nep141:wrap.near",
    "destination_asset": "nep141:usdt.tether-token.near",
    "amount": "1000000000000000000000000",
    "min_amount_out": "2000000"
  }'

const swap = await assistant.swap(
  agentId,
  {
    origin_asset: "nep141:wrap.near",
    destination_asset: "nep141:usdt.tether-token.near",
    amount: "1000000000000000000000000",
    min_amount_out: "2000000",
  },
  { idempotencyKey: "swap-user-123-1" },
);
console.log(swap.correlation_id, swap.status);

Withdraw

Sends funds out of NEAR Intents to an address on another chain, or to a NEAR account with chain: "near".

Field	Description
`asset`	The `asset_id` to send
`amount`	The amount, in atomic units. Must be greater than zero.
`chain`	The destination chain: any `blockchain` value `GET /v1/tokens` lists, such as `near`, `eth`, `base`, `sol`, `btc` or `tron`. Both routes reach every listed chain. Confidential withdrawals pay from the confidential balance (shield first) and deliver the same token symbol.
`recipient`	The address on `chain`. It must match a policy destination exactly when the destination rule is `only`.
`memo`	Optional. Required by some chains, and part of the destination match.
`confidential`	Optional. Withdraw from the confidential balance. Default `false`.
`async`	Optional. Return as soon as the bridge accepts the request and follow settlement with the status. Default `false`.
`dry`	Optional. `true` previews the received amount and the fee. See Swap quotes and withdrawal previews for when `fee` is `null`.

NEAR (nep141:wrap.near, or near) withdrawn to chain: "near" always arrives as native NEAR, from the public or the confidential balance, as it does from a NEAR wallet or 1Click. The recipient doesn’t need to register on wrap.near, and exchanges and payment invoices receive the NEAR they expect. A confidential withdrawal is paid out by 1Click, which unwraps it. There is no option to withdraw wNEAR to chain: "near".

A non-USDC asset withdrawn to chain: "hypercore" lands in HyperCore spot as that asset, not as USDC perps margin, and the preview warns with asset_delivered_as_is. Swap to USDC first to fund perps.

curl -X POST "$NEAR_INTENTS_AGENT_API_URL/v1/agents/$AGENT_ID/withdraw" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY" \
  -H "X-Grant-Token: $GRANT_TOKEN" \
  -H "Idempotency-Key: withdraw-user-123-1" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near",
    "amount": "5000000",
    "chain": "base",
    "recipient": "0x1111111111111111111111111111111111111111"
  }'

const withdrawal = await assistant.withdraw(
  agentId,
  {
    asset: "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near",
    amount: "5000000",
    chain: "base",
    recipient: "0x1111111111111111111111111111111111111111",
  },
  { idempotencyKey: "withdraw-user-123-1" },
);

Transfer

Sends funds to another NEAR Intents account.

Field	Description
`asset`	The `asset_id` to send
`amount`	The amount, in atomic units. Must be greater than zero.
`recipient`	The NEAR Intents account that receives the asset: a valid NEAR account id. A named account must exist on NEAR, because NEAR Intents credits any id and funds sent to an unregistered name cannot be recovered; otherwise the request is refused with `invalid_address` (400). Implicit ids (64 hex, or `0x` + 40 hex) need no account. If NEAR RPC cannot answer, the request is refused with retryable `near_rpc_unavailable` (503) and nothing is sent.
`confidential`	Optional. Transfer on the confidential balance. Default `false`.

const transfer = await assistant.transfer(
  agentId,
  { asset: "nep141:usdt.tether-token.near", amount: "1000000", recipient: "alice.near" },
  { idempotencyKey: "transfer-user-123-1" },
);

Shield and unshield

shield moves an asset from the public balance to the confidential balance. unshield moves it back. Both take { asset, amount }. See Funding.

Quote before you run

dry: true on swap and withdraw returns 200 with a quote instead of running the action. It runs nothing, charges no budget and reserves none. The account’s rules do not refuse it: each one the live request would fail comes back in warnings. An unlisted asset or an invalid recipient does refuse it, with 400. An archived, deleted or frozen account gets no quote. See Account rules in a quote.

A swap quote needs only your partner API key. It takes no Idempotency-Key.
A withdrawal preview needs X-Grant-Token, an Idempotency-Key and a policy that allows the withdrawal to that destination, like the withdrawal itself. The same key returns the same preview for 60 seconds; after that, withdraw_preview_expired means preview again under a new key. Each agent gets 20 previews per rolling 24 hours. Every preview that reaches the provider uses one, including ones that carry a rule warning; over that, withdraw_preview_limit_reached. A preview the provider refuses (for example route_unavailable), an outage and an uncertain attempt stay counted. Only an answer the provider gives before running anything (its rate limiter’s 429, wallet_busy, provider_limit_reached) gives its attempt back, and the same key may try again. The TypeScript SDK creates the key from 0.5.2.

curl -X POST "$NEAR_INTENTS_AGENT_API_URL/v1/agents/$AGENT_ID/swap" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_asset": "nep141:wrap.near",
    "destination_asset": "nep141:usdt.tether-token.near",
    "amount": "1000000000000000000000000",
    "dry": true
  }'

const quote = await api.swap(agentId, {
  origin_asset: "nep141:wrap.near",
  destination_asset: "nep141:usdt.tether-token.near",
  amount: "1000000000000000000000000",
  dry: true,
});
console.log(quote.type, quote.quote); // quote fields are snake_case, amounts are atomic strings

The response is

{ "dry": true, "type": "swap" | "withdraw", "quote": { … }, "spend": { … }, "fee": { … } | null, "warnings": [ … ], "owner_approval": boolean }

Field	Description
`quote`	The route’s quote, with snake_case fields and atomic amounts. Use its amounts to set `min_amount_out` on the real call.
`spend.amount_usd`	What the USD budget would count for this request. `null` when it would not be counted or its asset has no usable price.
`spend.budget`	`daily`, `weekly` and `monthly`, each `{ limit_usd, spent_usd, remaining_usd, resets_at }`, as `usage.budget` on `GET …/policy`, before this request. Every field is `null` for an uncapped window.
`fee`	`{ amount_usd, percent }`, or `null`. A swap compares the input’s value with the quoted output’s value at current prices. A withdrawal on chain `near` is valued from the provider’s `estimated_fee` when it is zero or its `fee_token` is the withdrawn asset, otherwise from `amount` minus `quote.amount_out` (on NEAR the route delivers the withdrawn asset itself, native NEAR in wNEAR’s units). A withdrawal to another chain delivers the asset of the same symbol 1Click lists there, and is valued from `amount` minus `quote.amount_out` in that asset. It is `null` when the quote states no `amount_out` (a public withdrawal’s preview) or the chain lists no single asset of that symbol; compare `amount` with what arrives yourself then.
`warnings`	A list of `{ code, detail }`. `high_fee`: the route keeps more than 5%, judged only where `fee` is valued. `asset_delivered_as_is`: a non-USDC asset withdrawn to chain `hypercore` lands in HyperCore spot as that asset, not as USDC perps margin. Swap to USDC first to fund perps. The other codes are spending rules the live request would fail: see Account rules in a quote.
`owner_approval`	`true` when the live request would wait in `PENDING_APPROVAL` until the owner approves it, because the applied policy’s `owner_approval` is on. It is not a warning: the request is accepted and held, and it counts against the budget while it waits.

Account rules in a quote

The account’s rules do not refuse a quote or preview. On a usable account it goes to the provider and returns 200 with the quote. It also checks what the live request would face, in this order: the policy’s action switch and destination rule, its assets, the schedule at the time the request would run (after timelock_ms), the USD budget, then per-asset limits and max_actions_per_hour, and last the balance. Each one the live request would fail is a warnings entry whose code is the code that request would get: policy_action_denied, policy_destination_denied, policy_asset_denied, policy_schedule_denied, spend_price_unavailable, spend_budget_exceeded, policy_limit_exceeded, policy_action_limit_exceeded, policy_usage_unavailable or insufficient_balance. A policy_schedule_denied warning also carries available_at, when the schedule next allows the request. An insufficient_balance warning carries available_amount, what the balance can still spend in atomic units. The live request is refused with these codes. The quote only warns. The request’s own checks do refuse the quote. An asset that GET /v1/tokens does not list (unsupported_token) or a recipient that is not a valid address (invalid_address) answers 400, as it does for the live request, because no quote can answer it. It is refused before any provider call and uses no preview attempt. An archived, deleted or frozen account gets no quote, because an account that can do nothing has no use for one. A swap quote and a withdrawal preview are both refused with 409 and the code the live request gets: agent_archived, agent_deleted or wallet_frozen. The refusal reaches no provider and uses no preview attempt. Read warnings before you execute. If any warning is one of these codes, the live request will be refused with that code. Tell the user, reduce the amount, wait (resets_at in spend.budget, or available_at) or ask the owner to change the policy. A quote without such a warning is a snapshot, not a guarantee. Other work can use the budget first, and a request held by timelock_ms is charged only when it is dispatched.

What happens to a call

Every execution passes these checks. A refusal names the layer that blocked it. Only a change to that layer lifts it. A dry: true quote or preview is not refused by these checks. It lists each one the live request would fail in warnings, under the same code.

Layer	Refusal	Who fixes it
Policy revision	`policy_not_ready`	Wait until the latest policy revision is `APPLIED`
Grant, action and destination	`agent_grant_required`, `policy_action_denied` (the action is off), `policy_destination_denied` (the destination rule), `wallet_frozen`	Your backend sends a live grant’s token. The owner changes the policy with `policy_update`, or unfreezes the agent.
Schedule	`policy_schedule_denied` with `meta.available_at`	Submit again at `meta.available_at`, or the owner changes the schedule
USD budget	`spend_budget_exceeded`, `spend_price_unavailable`	The owner raises a cap, or wait until its period ends (`resets_at`). See USD budget. Charged at the dispatch commitment.
Per-asset limits	`policy_limit_exceeded`, `policy_action_limit_exceeded`, `policy_usage_unavailable`	The owner raises the limit, or wait for earlier actions to leave the window. See Per-asset limits. Counted at the dispatch commitment.
Wallet provider’s policy	`policy_denied` (per-asset limits, assets, rate)	The owner changes the blocking rule. A larger USD budget never lifts it.
Wallet	`wallet_busy`, `insufficient_balance`	Wait, or fund the agent

Calls refused before the action is admitted leave nothing behind, so you can retry the same key after fixing the cause. That includes a new execution that exceeds the USD budget or a per-asset limit: if it runs now it is a plain refusal with no operation, no FAILED status and no charge, and the same key refuses again while the cause lasts. Refusals recorded for an admitted action (for example wallet_busy, a request that lost a concurrent race at the dispatch commitment, or a timelocked execution released over budget or a limit) are replayed under the same key. After the cause is fixed, send a new Idempotency-Key, unless the response carries meta.retryable: then the same key works after Retry-After. The error’s layer says whose rule it was: Error layers.

The dispatch commitment

An execution has a single point of no return, its dispatch commitment. The API reaches it right before it hands the action to the agent wallet, and dispatch_committed_at in the status shows when. The USD charge is decided in the same step. Before it, revoking a grant or an API key stops the action. After it, nothing can recall it.

Idempotency

Every execution needs an Idempotency-Key: 8 to 128 characters from A-Za-z0-9._:-. Retry with the same key and the same body to get the same operation back. Keys are scoped to the grant, and a new key is new work, so never use one to retry something UNCERTAIN or already dispatched. Status & Errors has the full rules. The SDK creates a key when you omit one and never retries a write by itself. To survive a crash, create the key, save it, then send:

import { createIdempotencyKey } from "@near-intents-agent-api/sdk";

const idempotencyKey = createIdempotencyKey();
// Persist idempotencyKey together with your own record, then send:
const result = await assistant.transfer(
  agentId,
  { asset: "nep141:usdt.tether-token.near", amount: "1000000", recipient: "alice.near" },
  { idempotencyKey },
);

One money action per wallet

The agent wallet runs one money action at a time. A second action that arrives while one is running is refused with wallet_busy (409). Wait for the first to settle, then send the second with a new Idempotency-Key, unless the response carries meta.retryable (then retry with the same key after Retry-After).

Timelock and the queue

When the policy has timelock_ms above zero, every execution except a deposit waits that long before it runs. The call returns at once with the status QUEUED.

{
  "correlation_id": "op_…",
  "agent_id": "…",
  "type": "transfer",
  "status": "QUEUED",
  "failure_code": null,
  "dispatch_committed_at": null,
  "grant": { "id": "…", "label": "Support assistant" },
  "details": { "action": "…", "provider_status": "timelocked", "execute_after": "2026-10-07T18:00:00.000Z", "delay_ms": 3600000 }
}

GET /v1/agents/{agent_id}/executions/scheduled lists what the timelock holds, earliest release first, as { correlation_id, execute_after, state, action }. state is waiting or dispatching. Page with cursor and limit.
The owner cancels a waiting execution with an execution_cancel intent that names its correlation_id. Once it is dispatching, the API answers execution_not_cancellable.
When the delay ends, the API checks the grant, the API key and the policy again. If any changed in the meantime, for example the owner revoked the grant or changed the policy, the execution fails with authorization_stale. Nothing was sent.
The schedule is judged when the action would run: after the delay for a new request, and again at release. Outside the schedule, the action is refused with policy_schedule_denied and meta.available_at.
The USD budget counts an execution when it dispatches, not when it was queued. A queued execution reserves nothing.

curl "$NEAR_INTENTS_AGENT_API_URL/v1/agents/$AGENT_ID/executions/scheduled?limit=25" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY"

const page = await api.listScheduledExecutions(agentId, { limit: 25 });
for (const item of page.data) console.log(item.correlation_id, item.execute_after, item.state);

Owner approval

When the policy has owner_approval: true, every execution waits for the owner’s vote before it moves funds. Deposits do not wait. The status reads PENDING_APPROVAL and details.approval_id names the request.

List what waits for approval

curl "$NEAR_INTENTS_AGENT_API_URL/v1/agents/$AGENT_ID/approvals" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY"

const approvals = await api.listApprovals(agentId);
for (const approval of approvals)
  console.log(approval.approval_id, approval.status, approval.request_type, approval.expires_at);

GET /v1/agents/{agent_id}/approvals/{approval_id} returns one request. Show request_type and request_data to the owner. An approval has an expires_at. After it, the status is EXPIRED.

The owner votes

The vote is an owner intent: approval_vote with the approval_id and a verdict of approve or reject. It needs the owner’s signature and no grant.

const vote = await api.generateIntent({
  type: "approval_vote",
  agent_id: agentId,
  approval_id: approvals[0]!.approval_id,
  verdict: "approve",
});
// The owner signs vote.intent.payload, then submit it like any owner intent.

owner_approval works for NEAR and passkey owners, and for EVM owners on deployments that enable EVM owners. EVM and passkey owners vote through their 0s wallet, with an EIP-712 or WebAuthn wallet authorization. While EVM is off, new EVM owners are refused at agent_create with owner_type_unsupported. Read supported_owner_types from GET /v1/network.

Vote errors: approval_signature_invalid (401), approval_not_allowed (403, the wallet policy does not admit the owner key or 0s wallet as approver), approval_vote_unsupported (409, the provider lists no such wallet build for this owner on this network, nothing was stored, ask the operator before voting again), approval_already_voted (409), approval_closed (409) and approval_not_found (404). See Status & Errors.

Recover an uncertain execution

Most UNCERTAIN executions need no action. Keep polling the same correlation_id. Never resend one under a new key. POST /v1/agents/{agent_id}/recover dispatches an UNCERTAIN execution once, but only when the API can prove it never reached the agent wallet: it has no provider reference and no dispatch commitment. Recovery is not an override for an action whose outcome is unknown. You send exactly what the first call sent: the same Idempotency-Key, the grant token of the grant that admitted it, the same API key, and the original body as request with its type.

curl -X POST "$NEAR_INTENTS_AGENT_API_URL/v1/agents/$AGENT_ID/recover" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY" \
  -H "X-Grant-Token: $GRANT_TOKEN" \
  -H "Idempotency-Key: swap-user-123-1" \
  -H "Content-Type: application/json" \
  -d '{
    "correlation_id": "'"$CORRELATION_ID"'",
    "request": {
      "type": "swap",
      "origin_asset": "nep141:wrap.near",
      "destination_asset": "nep141:usdt.tether-token.near",
      "amount": "1000000000000000000000000"
    }
  }'

const recovered = await assistant.recover(
  agentId,
  {
    correlation_id: correlationId,
    request: {
      type: "swap",
      origin_asset: "nep141:wrap.near",
      destination_asset: "nep141:usdt.tether-token.near",
      amount: "1000000000000000000000000",
    },
  },
  { idempotencyKey: "swap-user-123-1" }, // the original key
);

Code	Status	Meaning
`operation_not_recoverable`	409	The execution is not `UNCERTAIN`, already reached the agent wallet, was sent by another API key, was admitted without a grant, or is a deposit
`operation_recovery_unavailable`	409	Another recovery of this execution is running. Wait and check the status.
`idempotency_conflict`	409	`request` is not the original body, or the `Idempotency-Key` differs from the original

Recovery runs the checks again, so a revoked grant or a changed policy refuses it. Deposits cannot be recovered.

Agent API

Quickstart

Guides

Trust & Verification

API Reference

Run one action

The actions

Swap

Withdraw

Transfer

Shield and unshield

Quote before you run

Account rules in a quote

What happens to a call

The dispatch commitment

Idempotency

One money action per wallet

Timelock and the queue

Owner approval

Recover an uncertain execution

Next steps

Status & Errors

Policies & Limits

​Run one action

​The actions

​Swap

​Withdraw

​Transfer

​Shield and unshield

​Quote before you run

​Account rules in a quote

​What happens to a call

​The dispatch commitment

​Idempotency

​One money action per wallet

​Timelock and the queue

​Owner approval

​Recover an uncertain execution

​Next steps

Status & Errors

Policies & Limits

Run one action

The actions

Swap

Withdraw

Transfer

Shield and unshield

Quote before you run

Account rules in a quote

What happens to a call

The dispatch commitment

Idempotency

One money action per wallet

Timelock and the queue

Owner approval

Recover an uncertain execution

Next steps