Agent SDK

@near-intents-agent-api/sdk is a typed TypeScript client for the Agent API, for your backend. It has one method per endpoint, and its types are generated from the API’s OpenAPI document.

At a glance

Install: npm install @near-intents-agent-api/sdk (Node.js 24 or later, MIT licensed).
Runs on your backend: it holds your partner API key. Owner signing happens in your frontend with the owner’s own wallet. See Owner Signing.
Thin by design: no wallet signers, no React hooks, no browser entry point, no automatic retries, types only.
Optional: every endpoint is plain JSON over HTTPS, and every example in these docs also shows cURL.

Quick setup

Install the package

npm install @near-intents-agent-api/sdk

Create a client

.env

NEAR_INTENTS_AGENT_API_KEY=naa_...
NEAR_INTENTS_AGENT_API_URL=https://api.agentsonintents.com

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

const api = createAgentApi({
  apiKey: process.env.NEAR_INTENTS_AGENT_API_KEY!,
  baseUrl: process.env.NEAR_INTENTS_AGENT_API_URL, // optional, defaults to https://api.agentsonintents.com
});

Run it with node --env-file=.env your-script.ts.

Check the connection

const me = await api.whoami(); // validates the API key and never returns it
const network = await api.getNetwork(); // public: service and provider status
const tokens = await api.getTokens(); // public: every asset an agent can use

Common calls

Agent actions, under a grant

forGrant returns a client that sends X-Grant-Token on agent actions. Create one client per grant, so each assistant or bot always acts under its own grant and concurrent calls never borrow another grant’s token.

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

const { token, commitment } = createGrantCredential();
// The owner signs a grant_issue intent with `credential: commitment`.
// Store `token` encrypted on your backend. The API never sees it.

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

grantCommitment(token) returns the commitment of an existing token. See Grants for the full flow.

Owner actions

Owner actions follow one shape: generateIntent returns intent: { standard, payload }, the owner’s wallet signs payload unchanged, submitIntent sends the wallet’s output back, and getStatus follows the result.

const generated = await api.generateIntent({ type: "agent_freeze", agent_id: agentId });
// In your app this runs in the owner's browser and reaches your backend through your own route.
// See Owner Signing → The signing flow.
const signedData = await signWithWallet(generated.intent);

await api.submitIntent({
  type: generated.type,
  correlation_id: generated.correlation_id,
  signed_data: signedData,
});
const status = await api.getStatus(generated.correlation_id, { waitMs: 30_000 });

The SDK contains no signers. signWithWallet is your own wallet integration for NEAR, EVM and passkey owners. New EVM-owned agents are off by default and fail with owner_type_unsupported, so check getNetwork().supported_owner_types first. See Owner Signing.

Client options

Option	Default	Description
`apiKey`	required	Your `naa_…` partner API key. Sent as `X-API-Key`. Backend only.
`baseUrl`	`https://api.agentsonintents.com`	API origin, with no path. HTTPS, or HTTP for `localhost`.
`grantToken`	none	A grant token (`ngt_…`). Prefer `api.forGrant(token)`, which returns a separate client per grant.
`timeoutMs`	150 s for swap, withdraw, transfer, shield and unshield. 65 s for everything else, including dry swap and withdraw quotes.	Per-request timeout
`maxResponseBytes`	8 MiB	Response size limit, checked before JSON parsing, including errors
`fetch`	global `fetch`	Optional custom `fetch` for tests or instrumentation

Every method also takes { signal } to cancel it. Requests omit cookies and reject redirects.

Errors

Non-2xx responses throw AgentApiError. Branch on code, never on title or detail.

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

try {
  await api.submitIntent(submission);
} catch (error) {
  if (error instanceof AgentApiError && error.code === "policy_revision_conflict") {
    // Read the current policy, generate a fresh intent and ask for a new signature.
  }
  throw error;
}

Property	Description
`status`	HTTP status
`code`	Stable snake_case error code of the first error
`title`, `detail`	Human-readable text. Don’t branch on it.
`layer`	Whose rule refused: `request`, `auth`, `grant`, `policy`, `budget`, `balance`, `provider` or `api` (typed `ApiErrorLayer`). See Error layers. From SDK 0.7.
`retryable`	`true` when the identical request, with the same idempotency key, can succeed after a short wait, including after a server error whose request may have taken effect. `false` means repeating will not help now, not that nothing was sent: use a new key only after a refusal documented as sending nothing.
`availableAt`	When set, the earliest time to submit again, for rate limits and `policy_schedule_denied`
`retryAfterSeconds`	The response’s `Retry-After` header in whole seconds (seconds or an HTTP date on the wire), when it sent one. It is the API’s own wait for a throttle or outage whose end `availableAt` cannot name. From SDK 0.7.2.
`availableAmount`	On `insufficient_balance`, what the balance can still spend, in atomic units (`meta.available_amount`; the `available_raw` of the balances read). From SDK 0.7.
`minAmount`	On `amount_too_low`, the route minimum in atomic units of the asset sent, when the provider states it. From SDK 0.7; earlier versions read `errors[0].meta.min_amount`.
`requestId`	Request ID to share with support
`errors`	Every error entry. Validation failures return one per field.
`idempotencyKey`	The key transmitted with the request, when it had one

Transport, timeout, cancellation and parsing failures on a call sent with an idempotency key throw AgentApiRequestError, which keeps the key as idempotencyKey and the original error as cause. Calls without a key (reads, dry quotes, submitIntent and the native signing methods) throw the original error instead: a TypeError, TimeoutError, AbortError or SyntaxError. A response over the size limit throws AgentApiResponseTooLargeError, whose idempotencyKey is undefined on a call without a key. A failed write may still have reached the API, so reconcile the original operation before you retry it. See Status & Errors.

Idempotency

Every write that creates work (generateIntent, swap, withdraw, transfer, shield, unshield, deposit, recover, nativeNearTransfer and nativeNearCall) carries an Idempotency-Key. If you omit it, the SDK generates one and returns it with the result as result.idempotencyKey. To survive a crash, create and store the key before you send:

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

const idempotencyKey = createIdempotencyKey();
await saveRequest({ agentId, request, idempotencyKey }); // your durable storage
await assistant.transfer(agentId, request, { idempotencyKey });

To retry, send the same body with the same key. The original result comes back. The SDK never retries by itself. A request with a new key is new work, so never use one to retry an UNCERTAIN operation. recover requires the original key. Swap quotes (swap with dry: true), reads and submitIntent need no key. A withdrawal preview (withdraw with dry: true) carries one like the withdrawal; from SDK 0.5.2 the SDK creates it unless you pass idempotencyKey.

Pagination

Lists that can grow return { data, next_cursor }. Pass next_cursor back as cursor until it’s null.

let cursor: string | undefined;
do {
  const page = await api.getHistory(agentId, { limit: 50, cursor });
  for (const entry of page.data) console.log(entry.correlation_id, entry.type, entry.status);
  cursor = page.next_cursor ?? undefined;
} while (cursor);

listGrants, listApprovals and getTokens return the plain array. getPolicyHistory uses a numeric cursor, and getContainment takes grants_cursor and operations_cursor.

Types

Every request, response and view type is exported: Policy, OwnerWallet, AgentView, StatusResponse, GenerateIntentRequest, SwapRequest and the rest. getStatus returns a union discriminated by type. Narrow on status.type before you read status.details, or use StatusResponseOf<"swap">.

const status = await api.getStatus(execution.correlation_id);
if (status.type === "swap") console.log(status.details.amount_out);

The package ships types only. To validate responses at runtime or to build a client in another language, generate one from the API’s OpenAPI document, https://api.agentsonintents.com/openapi.json.

Methods

Method names and SDK options (waitMs, idempotencyKey, signal) are camelCase. Request bodies, query parameters and response fields are snake_case, exactly as on the wire.

Owner intents and status

Method	Endpoint
`generateIntent(request, { idempotencyKey?, signal? })`	`POST /v1/generate-intent`
`submitIntent({ type, correlation_id, signed_data }, { signal? })`	`POST /v1/submit-intent`
`getStatus(correlationId, { waitMs?, refresh?, signal? })`	`GET /v1/status`
`getHistory(agentId, { cursor?, limit?, include_unpaid? })`	`GET /v1/agents/{agent_id}/history`

Agents and balances

Method	Endpoint
`listAgents({ external_user_id?, cursor? })`	`GET /v1/agents`
`getAgent(agentId)`	`GET /v1/agents/{agent_id}`
`getWallet(agentId)`	`GET /v1/agents/{agent_id}/wallet`
`getBalances(agentId, { source?, asset? })`	`GET /v1/agents/{agent_id}/balances`
`getAddress(agentId, "near")`	`GET /v1/agents/{agent_id}/addresses/{chain}`
`getContainment(agentId, { grants_cursor?, operations_cursor? })`	`GET /v1/agents/{agent_id}/containment`
`listProviderRecords(agentId, kind, { limit?, offset?, type? })`	`GET /v1/agents/{agent_id}/provider/{kind}`

Rules and access

Method	Endpoint
`getPolicy(agentId)`	`GET /v1/agents/{agent_id}/policy`
`getPolicyHistory(agentId, { cursor?, limit? })`	`GET /v1/agents/{agent_id}/policy/history`
`listGrants(agentId)`	`GET /v1/agents/{agent_id}/grants`
`listApprovals(agentId)`	`GET /v1/agents/{agent_id}/approvals`
`getApproval(agentId, approvalId)`	`GET /v1/agents/{agent_id}/approvals/{approval_id}`
`listScheduledExecutions(agentId, { cursor?, limit? })`	`GET /v1/agents/{agent_id}/executions/scheduled`

Agent actions (need a grant)

Method	Endpoint
`swap(agentId, request, options)`	`POST /v1/agents/{agent_id}/swap`
`withdraw(agentId, request, options)`	`POST /v1/agents/{agent_id}/withdraw`
`transfer(agentId, request, options)`	`POST /v1/agents/{agent_id}/transfer`
`shield(agentId, request, options)`	`POST /v1/agents/{agent_id}/shield`
`unshield(agentId, request, options)`	`POST /v1/agents/{agent_id}/unshield`
`recover(agentId, request, { idempotencyKey })`	`POST /v1/agents/{agent_id}/recover`
`nativeNearSignMessage(agentId, { message, recipient, nonce, encoding? })`	`POST /v1/agents/{agent_id}/native/near/sign-message`
`nativeNearTransfer(agentId, request, options)`	`POST /v1/agents/{agent_id}/native/near/transfer`
`nativeNearCall(agentId, request, options)`	`POST /v1/agents/{agent_id}/native/near/call`
`nativeEvmSignTypedData(agentId, request)`	`POST /v1/agents/{agent_id}/native/evm/sign-typed-data`
`nativeEvmSignMessage(agentId, request)`	`POST /v1/agents/{agent_id}/native/evm/sign-message`
`nativeEvmSignTransaction(agentId, request)`	`POST /v1/agents/{agent_id}/native/evm/sign-transaction`
`nativeSolanaSignMessage(agentId, request)`	`POST /v1/agents/{agent_id}/native/solana/sign-message`
`nativeSolanaSignTransaction(agentId, request)`	`POST /v1/agents/{agent_id}/native/solana/sign-transaction`

swap with dry: true returns a quote and needs no grant and no idempotency key. withdraw with dry: true previews the received amount under the grant and an idempotency key, at most 20 times per agent per rolling 24 hours; fee is null when the preview cannot value what arrives (a public bridged withdrawal states no amount_out). Neither the account’s rules (action, destination, schedule, USD budget, per-asset limits) nor the balance (insufficient_balance) refuse either. An unlisted asset (unsupported_token) or an invalid recipient (invalid_address) throws before any provider call and uses no preview attempt. An archived, deleted or frozen account gets no quote: it is refused with agent_archived, agent_deleted or wallet_frozen. The answer adds spend, fee and warnings to { dry, type, quote }, and each rule the live request would fail is a warning under that request’s code. See Executions. The native… methods use the agent’s own NEAR, EVM and Solana keys outside NEAR Intents, each off until the policy’s native block switches it on. nativeNearTransfer and nativeNearCall take an idempotency key; the signing methods answer at once. SDK 0.5.3 replaces sign with nativeNearSignMessage. See Native Accounts.

Funding

Method	Endpoint
`deposit(agentId, request, options)`	`POST /v1/agents/{agent_id}/deposit`

deposit creates an incoming deposit address. It needs only the API key, no grant. Its amount is optional. A failed or late deposit refunds into the agent’s own balance, reported as details.refund_to.

Transparency

Method	Endpoint
`getOperationProof(agentId, correlationId)`	`GET /v1/agents/{agent_id}/operations/{correlation_id}/proof`

verifyOperationProof(proof, origin) checks a proof offline and throws NoteError or ProofError when it doesn’t hold. See Transparency Proofs.

Account and service

Method	Endpoint
`whoami()`	`GET /v1/whoami`
`getPartnerQuota()`	`GET /v1/quotas`
`getNetwork()`	`GET /v1/network`
`getTokens()`	`GET /v1/tokens`

getPartnerQuota() reports how many agents and API keys you may create and what you’ve used. getNetwork() and getTokens() are public.

Helpers

Helper	Description
`createGrantCredential()`	A new grant token and its commitment
`grantCommitment(token)`	The commitment of an existing grant token
`createIdempotencyKey()`	A new idempotency key
`api.forGrant(token)`	A client that runs agent actions under one grant
`DEFAULT_BASE_URL`	`https://api.agentsonintents.com`

Behavior

No automatic retries. The SDK never retries a request. Retry a write yourself with the same idempotencyKey and body.
Long polling. getStatus accepts waitMs up to 30,000. A poll can return a non-terminal status. Keep polling with the same correlation_id. After NEEDS_REVIEW is resolved, call getStatus(id, { refresh: true }).
Typed results. Writes that take an idempotency key return the response plus idempotencyKey. getStatus returns a union discriminated by type.

Quickstart

Build the full flow with these methods.

Examples

Runnable scripts for every flow, with the SDK and with plain HTTP.

Agent API

Quickstart

Guides

Trust & Verification

API Reference

Quick setup

Common calls

Agent actions, under a grant

Owner actions

Client options

Errors

Idempotency

Types

Methods

Behavior

Quickstart

Examples

​Quick setup

​Common calls

​Agent actions, under a grant

​Owner actions

​Client options

​Errors

​Idempotency

​Pagination

​Types

​Methods

​Behavior

Quickstart

Examples

Quick setup

Common calls

Agent actions, under a grant

Owner actions

Client options

Errors

Idempotency

Pagination

Types

Methods

Behavior