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). Current version: 0.9.1.
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=<your partner API key>
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 partner API key from the partner portal, an opaque string. 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, `placeLimitOrder`, withdraw, transfer and shield. 65 s for everything else, including dry swap, limit-order 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, placeLimitOrder, withdraw, transfer, shield, 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), limit-order previews (placeLimitOrder with dry: true), reads, the limit-order cancels 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 (listApprovals drops the listing’s truncated flag; see Owner approval). listLimitOrders takes limit and offset and returns { data } with no next_cursor: raise offset until a page is empty. 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, LimitOrderRequest, LimitOrderView 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}`
`listLimitOrders(agentId, { open?, limit?, offset? })`	`GET /v1/agents/{agent_id}/limit-orders`
`getLimitOrder(agentId, orderId)`	`GET /v1/agents/{agent_id}/limit-orders/{order_id}`

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`
`placeLimitOrder(agentId, request, options)`	`POST /v1/agents/{agent_id}/limit-orders`
`cancelLimitOrder(agentId, orderId)`	`POST /v1/agents/{agent_id}/limit-orders/{order_id}/cancel`
`cancelAllLimitOrders(agentId)`	`POST /v1/agents/{agent_id}/limit-orders/cancel-all`
`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`. Always refused with `public_balance_exit_only`.
`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`
`nativeEvmSignIntent(agentId, { payload, one_click_quotes? })`	`POST /v1/agents/{agent_id}/native/evm/sign-intent`
`nativeEvmSignTransaction(agentId, request)`	`POST /v1/agents/{agent_id}/native/evm/sign-transaction`
`nativeSolanaSignIn(agentId, request)`	`POST /v1/agents/{agent_id}/native/solana/sign-in`
`nativeSolanaSignMessage(agentId, request)`	`POST /v1/agents/{agent_id}/native/solana/sign-message`
`nativeSolanaSignIntent(agentId, { payload, one_click_quotes? })`	`POST /v1/agents/{agent_id}/native/solana/sign-intent`
`nativeSolanaSignTransfer(agentId, { unsigned_tx, recipient })`	`POST /v1/agents/{agent_id}/native/solana/sign-transfer`
`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. placeLimitOrder with dry: true is the same for a limit order and returns a QuoteResponse whose warnings list every rule a live order would fail; the live call answers SUCCESS once the order is funded and resting, not filled. listLimitOrders answers { data }, not an unwrapped array. See Limit Orders. withdraw with dry: true previews the received amount under the grant and an idempotency key; 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. 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.From SDK 0.7.4, nativeEvmSignIntent and nativeSolanaSignIntent sign a NEAR Intents payload (canonical JSON text, transfer intents only, signed for the key’s own Intents account) under the policy’s native.evm.sign_intent or native.solana.sign_intent rules, and answer IntentSignature: a signature plus signed_data to publish as is. nativeSolanaSignIn signs a Sign-In-With-Solana login for a domain in native.solana.sign_in and answers SolanaSignIn, with signed_message, the exact text signed. nativeSolanaSignTransfer signs one SOL or SPL transfer to a recipient that destinations allows, under native.solana.sign_transfer, and answers NativeSignature. From SDK 0.8.2 they take one_click_quotes: up to 2 of 1Click’s POST /v0/quote answers, unchanged, one per 1Click deposit address the payload pays outside receivers, typed OneClickQuote. The rule types are SignIntentRules, EvmSignIntentRequest, SolanaSignIntentRequest, SolanaSignInRequest and SolanaSignTransferRequest. A freeze refuses new payloads but cannot recall one already signed. 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, { from_size })`	`GET /v1/agents/{agent_id}/operations/{correlation_id}/proof`

verifyOperationProof(proof, origin, trusted) checks a proof offline against a trusted checkpoint and throws NoteError or ProofError when it doesn’t hold. From SDK 0.8.0 it requires trusted, and fetchWitnessCheckpoint(apiUrl, origin, witnessPublicKey) fetches a fresh one from the witness on front-1; pin the key yourself. Pass from_size (the trusted checkpoint’s size, as a decimal string) to getOperationProof to receive a consistency proof from it. Earlier versions verify with two arguments, which predates this check. 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 your agent and request limits 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