Execute Actions

The owner doesn’t sign agent actions. A spending action carries three things instead: your partner API key (X-API-Key), the grant token (X-Grant-Token) and an Idempotency-Key. Each action returns a correlation_id. You follow it with GET /v1/status until it settles. Two things don’t need a grant: creating a deposit address, and swap quotes (dry: true).

Prerequisites

An ACTIVE agent with a live policy from Create an Agent, saved as AGENT_ID.
A grant token from Issue a Grant, saved as GRANT_TOKEN.
About 10 USDC on Base to send.

Every snippet below assumes this setup:

execute.ts

import { AgentApiError, AgentApiRequestError, createIdempotencyKey } from "@near-intents-agent-api/sdk";
import { api, settled } from "./agent-api.ts";

const USDC_BASE = "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near";
const USDT_NEAR = "nep141:usdt.tether-token.near";
const agentId = process.env.AGENT_ID!;
const ownerAccountId = process.env.OWNER_ACCOUNT_ID!;

// One client per grant. It sends X-Grant-Token on the calls that need it.
const assistant = api.forGrant(process.env.GRANT_TOKEN!);

Fund the agent

Ask for a one-time deposit address. This needs only your API key and an Idempotency-Key: no grant, no owner signature, and no policy destination, budget or delay applies. Funds are credited to the agent’s own account. In this example, the agent receives 10 USDC from Base.origin_asset is the exact asset_id of the token you send, which fixes both the chain and the token. amount is optional. Without it, the address credits any payment at or above details.min_amount until details.expires_at.

curl -X POST "$NEAR_INTENTS_AGENT_API_URL/v1/agents/$AGENT_ID/deposit" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deposit-user-123-1" \
  -d '{
    "origin_asset": "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near",
    "amount": "10000000"
  }'

const deposit = await api.deposit(agentId, { origin_asset: USDC_BASE, amount: "10000000" }); // 10 USDC
const { details } = deposit;
console.log(deposit.status, details.deposit_address, details.memo, details.min_amount, details.expires_at);

// Send the funds, then follow the deposit.
const funded = await settled(deposit.correlation_id);
console.log(funded.status);

The status is PENDING_DEPOSIT. Send the USDC on Base to details.deposit_address, with details.memo if it’s set, before details.expires_at.

Field	Description
`details.deposit_address`	The only place to send funds. A `correlation_id` is never an address. If this field is missing, send nothing.
`details.memo`	Send it with the deposit on chains that require one
`details.min_amount`	The smallest deposit that is credited, in atomic units
`details.expires_at`	Funds arriving later are refunded
`details.refund_to`	The agent’s own account. A wrong amount, a late payment or a failed conversion refunds there.

There’s no refund address to choose. A new key creates a new address, so keep the key and reuse it to retry: the same key returns the same address. You can also fund the agent with a transfer from any NEAR Intents account to agent.wallet.near_account_id.

Check balances

curl "$NEAR_INTENTS_AGENT_API_URL/v1/agents/$AGENT_ID/balances?source=public" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY"

const { balances } = await api.getBalances(agentId, { source: "public" });
for (const balance of balances) console.log(balance.symbol, balance.balance, balance.balance_raw);

Example response

{
  "near_account_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "source": "public",
  "balances": [
    {
      "asset_id": "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near",
      "symbol": "USDC",
      "decimals": 6,
      "blockchain": "base",
      "price": 0.999756,
      "price_updated_at": "2026-10-07T17:08:00.591Z",
      "price_expires_at": "2026-10-07T17:18:00.591Z",
      "balance_raw": "10000000",
      "balance": "10",
      "available_raw": "10000000",
      "available": "10"
    }
  ]
}

Use balance_raw, in atomic units, for arithmetic and request amounts. balance is the exact decimal amount for display. available_raw and available are what a new request can still spend: the balance less queued or timelocked work not yet dispatched. Read them instead of working it out yourself. Use source=confidential for the confidential balance.

Quote a swap

Add dry: true to see the price without swapping. A quote needs no grant token and no idempotency key. It returns 200 instead of 202, moves nothing and charges no budget. The spending rules never refuse it, but they are checked: if the live swap would be refused for the schedule, budget or a limit, warnings says so with the same code. A frozen, archived or deleted account gets no quote.

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:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near",
    "destination_asset": "nep141:usdt.tether-token.near",
    "amount": "5000000",
    "dry": true
  }'

const quote = await api.swap(agentId, {
  origin_asset: USDC_BASE,
  destination_asset: USDT_NEAR,
  amount: "5000000", // 5 USDC
  dry: true,
});
console.log(quote.quote);

The response is { "dry": true, "type": "swap", "quote": { … }, "spend": { … }, "fee": { … } | null, "warnings": [ … ] }. quote holds the route’s quote with snake_case fields and atomic amounts. spend shows what the USD budget would count and the budget left, fee what the route keeps, and warnings lists high_fee above 5% and any account rule the live swap would fail. See Executions. Check warnings before you execute. A quote without a rule warning is a snapshot, not a guarantee: other work can use the budget first.If a quote fails with provider_unavailable (the quote service did not answer), nothing was submitted. Check GET /v1/network, wait until one_click reports operational, and try again. route_unavailable means no route or liquidity for this pair or amount: try a different amount or pair under a new Idempotency-Key, since repeating the request will not help. A rule such as spend_budget_exceeded or policy_schedule_denied, or a balance too small for the amount (insufficient_balance, with available_amount), does not fail the quote. It appears in warnings, and the live swap is refused with that code.

Execute the swap

Send the same body without dry, and add the grant token and an Idempotency-Key. Optionally add min_amount_out, the minimum output sent to the provider. The quote does not apply it, and a swap reported below it never reads SUCCESS but NEEDS_REVIEW with amount_out_below_minimum. Create and store the key before you send, so a crash never leaves you guessing.

CORRELATION_ID=$(curl -s -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 "Content-Type: application/json" \
  -H "Idempotency-Key: swap-user-123-1" \
  -d '{
    "origin_asset": "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near",
    "destination_asset": "nep141:usdt.tether-token.near",
    "amount": "5000000",
    "min_amount_out": "4900000"
  }' | jq -r .correlation_id)

curl "$NEAR_INTENTS_AGENT_API_URL/v1/status?correlation_id=$CORRELATION_ID&wait_ms=30000" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY"

const swap = await assistant.swap(agentId, {
  origin_asset: USDC_BASE,
  destination_asset: USDT_NEAR,
  amount: "5000000",
  min_amount_out: "4900000",
});
// swap.idempotencyKey is the key the SDK generated. Reuse it to retry this exact request.

const swapped = await settled(swap.correlation_id);
if (swapped.type === "swap") console.log(swapped.status, swapped.details.amount_out); // amount_out is set once the status is SUCCESS

Example status

{
  "correlation_id": "op_Yp7mQ2xK9vRtL4nB8cD1fG5hJ3sWaE6uZoT0iNyXk2M",
  "agent_id": "6f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d",
  "type": "swap",
  "status": "SUCCESS",
  "failure_code": null,
  "created_at": "2026-10-07T11:06:00.000Z",
  "updated_at": "2026-10-07T11:06:14.000Z",
  "dispatch_committed_at": "2026-10-07T11:06:01.000Z",
  "grant": { "id": "9e8d7c6b5a49382716051f2e3d4c5b6a7980f1e2d3c4b5a69788796a5b4c3d2e", "label": "Quickstart assistant" },
  "details": {
    "action": "swap",
    "intent_hash": "5Kd8Yt3pQw9xVn2mR7sB4cF6gH1jL3kN5pT8vW2yZ4a",
    "amount_out": "4995012"
  }
}

If the policy, destination rule, budget or grant refuses the request, you get an error and the swap never runs. A budget or limit refusal records nothing and charges nothing. The error code says what refused and its layer whose rule it was. See Status & Errors.

Transfer and withdraw

The policy lets the agent send only to alice.near, so these two actions use the owner’s account. A transfer goes to another NEAR Intents account. A withdraw goes to an address on any chain the route reaches, so it also takes chain. Preview a withdrawal first with dry: true. A preview runs under the grant and an idempotency key, like the withdrawal, and each agent gets 20 previews per rolling 24 hours. Every preview that reaches the provider uses one, even when it carries a rule warning.

curl -X POST "$NEAR_INTENTS_AGENT_API_URL/v1/agents/$AGENT_ID/transfer" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY" \
  -H "X-Grant-Token: $GRANT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: transfer-user-123-1" \
  -d '{
    "asset": "nep141:usdt.tether-token.near",
    "amount": "1000000",
    "recipient": "alice.near"
  }'

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 "Content-Type: application/json" \
  -H "Idempotency-Key: withdraw-user-123-1" \
  -d '{
    "asset": "nep141:usdt.tether-token.near",
    "amount": "1000000",
    "chain": "near",
    "recipient": "alice.near"
  }'

const transfer = await assistant.transfer(agentId, {
  asset: USDT_NEAR,
  amount: "1000000", // 1 USDT
  recipient: ownerAccountId,
});
console.log((await settled(transfer.correlation_id)).status);

const withdrawal = { asset: USDT_NEAR, amount: "1000000", chain: "near", recipient: ownerAccountId };
const preview = await assistant.withdraw(agentId, { ...withdrawal, dry: true }); // the SDK sends a key
console.log(preview.quote);

const withdrawn = await assistant.withdraw(agentId, withdrawal);
console.log((await settled(withdrawn.correlation_id)).status);

An address the policy’s destinations rule doesn’t list fails with policy_destination_denied. For a withdrawal, the chain, address and memo must match a listed entry exactly. To allow a new destination, the owner signs a policy_update, and every live grant can use it at once. Amounts below the route’s minimum fail with amount_too_low.

Follow every action to its result

Every action returns 202 with a correlation_id. Poll GET /v1/status with it. These are the statuses you handle:

Status	What to do
`QUEUED`, `PROCESSING`	Keep polling. `QUEUED` waits for the policy’s `timelock_ms`. A withdrawal waiting on 1Click reads `PROCESSING`.
`PENDING_DEPOSIT`	A deposit address waiting for incoming funds. Send them. Only deposits report it.
`PENDING_APPROVAL`	Waiting for the owner’s approval vote, when the policy has `owner_approval`.
`SUCCESS`	Done, backed by reconciled evidence.
`FAILED`, `REFUNDED`	Ended without the intended result. Read `failure_code`.
`UNCERTAIN`	The outcome is not yet proven. Keep polling the same `correlation_id`.
`NEEDS_REVIEW`	Automatic settlement stopped. Read `details.reason` and don’t retry.

An UNCERTAIN action may already have executed. Never send it again under a new Idempotency-Key, or it may run twice. Keep polling the original correlation_id. A request that fails with a network error may also have reached the API: retry it with the same key and the same body, and you get the original result.

TypeScript SDK

const request = { asset: USDT_NEAR, amount: "1000000", recipient: ownerAccountId };
const idempotencyKey = createIdempotencyKey(); // save it with the request before you send

async function sendTransfer() {
  try {
    const execution = await assistant.transfer(agentId, request, { idempotencyKey });
    return await settled(execution.correlation_id);
  } catch (error) {
    if (error instanceof AgentApiRequestError) {
      // Network failure or timeout. The request may have been accepted: same key, same body.
      const retried = await assistant.transfer(agentId, request, { idempotencyKey: error.idempotencyKey });
      return await settled(retried.correlation_id);
    }
    if (error instanceof AgentApiError) {
      // Branch on error.code, never on error.title. Include error.requestId when you contact support.
      console.log(error.status, error.code, error.retryable, error.availableAt, error.requestId);
    }
    throw error;
  }
}

A request that may have reached the wallet usually answers with status UNCERTAIN, but a server error can also follow a send. If error.retryable is true, send the same request with the same key after the wait: that covers server errors too, where the request may have taken effect. Without it, repeating will not help, but that alone does not prove nothing was sent. Codes such as spend_budget_exceeded or wallet_busy are refusals that sent nothing: the key replays the refusal and a later attempt needs a new key. After a server error or a lost response, keep the original key and read the status. availableAt is the earliest time to try again after a schedule or rate-limit refusal. The agent runs one money action at a time, so a second action sent while one runs fails with wallet_busy.For NEEDS_REVIEW, and for the full list of error codes, see Status & Errors.

You’ve now run the full path: an agent funded by a deposit, swapped inside rules its owner signed, and paid out. What the grant could do was always bounded by the policy.

Other actions

Action	Endpoint	Notes
Shield	`POST …/shield`	Move funds from the agent’s public balance to its private balance. The policy needs `confidential: true`.
Unshield	`POST …/unshield`	Move funds from the private balance back to the public balance
Recover	`POST …/recover`	First dispatch of an `UNCERTAIN` action that provably never reached the provider. It needs the original idempotency key and the grant. It’s not an override for uncertainty.

swap, withdraw, transfer and deposit also accept confidential: true to use the private balance. A private request never falls back to a public one.

You now have a funded agent that has swapped, transferred and withdrawn inside its owner’s rules, with each action followed to SUCCESS. That’s the whole flow.

Policies & Limits

Change the rules, budget, delay and schedule the owner signs.

Agent SDK

Every method, option and error field of the TypeScript client.

Agent API

Quickstart

Guides

Trust & Verification

API Reference

Prerequisites

Other actions

Policies & Limits

Agent SDK

​Prerequisites

​Other actions

Policies & Limits

Agent SDK

Prerequisites

Other actions