Quickstart

This quickstart takes an agent from nothing to a funded account that swaps and pays out inside rules its owner signed. Plan on about 30 minutes and about 10 USDC on Base. The owner signs twice; everything after that runs from your backend.

Page	About	You end with
Set up (this page)	5 min	The SDK, a `.env` and a shared client
Create an Agent	10 min	An `ACTIVE` agent and its `AGENT_ID` (owner signature 1)
Issue a Grant	5 min	A `GRANT_TOKEN` (owner signature 2)
Execute Actions	10 min	A funded agent that has swapped, transferred and withdrawn

There is no testnet version of NEAR Intents or the Agent API. Everything here runs on mainnet with real funds, so use a dedicated owner account and small amounts.

What you’ll build

Create an agent (owner signature 1 of 2)

The owner signs one complete policy. The agent becomes ACTIVE with its own wallet.

Issue a grant (owner signature 2 of 2)

Your backend creates a grant token. The owner signs its commitment, which says who may act for the agent. That is the owner’s last signature in this quickstart.

Fund the agent

Your backend asks for a deposit address and sends USDC to it. No grant and no owner signature are needed.

Swap, transfer and withdraw

Your backend quotes and runs the actions with the grant token, then follows each one to SUCCESS.

Prerequisites

Node.js 24 or later. Every step also shows cURL.
A partner API key. Create one in the Partner Dashboard. It starts with naa_ and is shown once. See Partner API Key.
An owner wallet to sign with: a NEAR account or a passkey. The snippets use a NEAR account, alice.near. EVM wallets work only where GET /v1/network lists evm in supported_owner_types, and they aren’t enabled by default. See Owner Signing for the other wallets.
About 10 USDC on Base, sent from any wallet, to fund the agent.

Owner signing runs in your frontend with the owner’s own wallet. The SDK has no wallet signers, so the signing step shows the wallet code you add to your app. To run this whole flow from one script with a throwaway key instead, use the runnable examples.

Set up your backend

Install the SDK

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

Set your environment

Keep the partner API key out of git and out of every browser. The other values come from the pages that follow.

.env

NEAR_INTENTS_AGENT_API_KEY=naa_...
NEAR_INTENTS_AGENT_API_URL=https://api.agentsonintents.com
OWNER_ACCOUNT_ID=alice.near
OWNER_PUBLIC_KEY=ed25519:...
# Set after "Create an Agent":
AGENT_ID=
# Set after "Issue a Grant":
GRANT_TOKEN=

Run every script with node --env-file=.env script.ts. For cURL, load the file with set -a; source .env; set +a.

Create the shared client

The client talks to NEAR_INTENTS_AGENT_API_URL, or to https://api.agentsonintents.com when it isn’t set. settled follows an operation until it stops moving. Each getStatus call waits up to 30 seconds for a change.

agent-api.ts

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

export const api = createAgentApi({
  apiKey: process.env.NEAR_INTENTS_AGENT_API_KEY!,
  baseUrl: process.env.NEAR_INTENTS_AGENT_API_URL,
});

// These statuses move on their own. UNCERTAIN is one of them: the outcome is not yet proven,
// so you keep polling the same correlation_id.
const pending = new Set(["PROCESSING", "QUEUED", "PENDING_DEPOSIT", "PENDING_APPROVAL", "UNCERTAIN"]);

export async function settled(correlationId: string, timeoutMs = 10 * 60_000): Promise<StatusResponse> {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const status = await api.getStatus(correlationId, { waitMs: 30_000 });
    if (!pending.has(status.status)) return status;
  }
  throw new Error(`${correlationId} is still pending. Keep polling the same correlation_id.`);
}

The .ts imports in the later pages run on Node 24 as they are.

Check your key

GET /v1/whoami confirms the key works. It returns your key ID and tenant ID, never the key. GET /v1/network is public and reports whether the services the API depends on are healthy. It’s advisory and about a minute old at most. Check it first whenever a quote or route fails.

curl "$NEAR_INTENTS_AGENT_API_URL/v1/whoami" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY"

curl "$NEAR_INTENTS_AGENT_API_URL/v1/network"

import { api } from "./agent-api.ts";

const me = await api.whoami();
console.log(me.api_key_id, me.tenant_id);

const network = await api.getNetwork();
console.log(network.status.overall); // operational, degraded, down or unknown

Example responses

whoami

{
  "api_key_id": "0b5c2f1e8a474d3e9a615f2c7d8e9a10b3c4d5e6f708192a3b4c5d6e7f8091a2",
  "tenant_id": "6c1d2e3f4a5b4c6d8e7f0a1b2c3d4e5f60718293a4b5c6d7e8f9011223344556"
}

network

{
  "network": "mainnet",
  "contract_id": "outlayer.near",
  "supported_owner_types": ["near", "passkey"],
  "status": {
    "overall": "operational",
    "checked_at": "2026-10-07T17:08:02.107Z",
    "components": [
      { "id": "one_click", "status": "operational", "reason": null, "affects": ["swap", "withdraw", "deposit"], "since": "2026-10-07T16:42:02.388Z", "checked_at": "2026-10-07T17:08:02.388Z" },
      { "id": "custody", "status": "operational", "reason": null, "affects": ["swap", "withdraw", "transfer", "shield", "unshield", "deposit", "owner_intents"], "since": "2026-10-07T16:42:02.125Z", "checked_at": "2026-10-07T17:08:02.107Z" },
      { "id": "near", "status": "operational", "reason": null, "affects": ["owner_intents"], "since": "2026-10-07T16:42:02.118Z", "checked_at": "2026-10-07T17:08:02.110Z" }
    ]
  }
}

A 401 with invalid_api_key means the key is wrong, revoked or has stray whitespace. GET /v1/quotas (api.getPartnerQuota()) shows how many agents and keys you can create and what you’ve used.

Start building

Create an Agent

Sign one complete policy and wait for the agent to go live.

Issue a Grant

Create a grant token and have the owner sign its commitment.

Execute Actions

Fund the agent, quote and run a swap, then transfer and withdraw.

Status & Errors

Read statuses, retry safely and handle error codes.

Agent API

Guides

Trust & Verification

API Reference

Quickstart

What you’ll build

Prerequisites

Set up your backend

Check your key

Start building

Create an Agent

Issue a Grant

Execute Actions

Status & Errors

​What you’ll build

​Prerequisites

​Set up your backend

​Check your key

​Start building

Create an Agent

Issue a Grant

Execute Actions

Status & Errors

What you’ll build

Prerequisites

Set up your backend

Check your key

Start building