Create an Agent

Creating an agent is an owner action. It takes one owner signature:

Your backend asks the API for the payload to sign. The request carries the complete policy.
The owner’s wallet signs intent.payload exactly as returned.
Your backend submits the signature and waits until the agent is ACTIVE.

Prerequisites

The setup and key check from the introduction, including agent-api.ts.
OWNER_ACCOUNT_ID and OWNER_PUBLIC_KEY in .env: a NEAR account and the public key of one of its full-access keys.

Find your tokens

GET /v1/tokens lists every token an agent can hold and trade. It’s public, so it needs no key. Note the asset_id of each token you want. You use these IDs in the policy and in every action.

curl "$NEAR_INTENTS_AGENT_API_URL/v1/tokens"

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

const tokens = await api.getTokens();

This quickstart uses USDC on Base and USDT on NEAR:

Token	`asset_id`	Decimals
USDC (Base)	`nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near`	6
USDT (NEAR)	`nep141:usdt.tether-token.near`	6

Amounts in the API are always whole numbers in the token’s smallest unit, as strings. With decimals: 6, 1 USDC is "1000000". price is the USD price, or null when there’s no recent one. Treat null as unknown, not zero.

Describe the owner

The owner is the wallet that controls the agent. Only public data goes here, never a private key.

{
  "type": "near",
  "account_id": "alice.near",
  "public_key": "ed25519:YOUR_FULL_ACCESS_PUBLIC_KEY"
}

{
  "type": "passkey",
  "credential_id": "BASE64URL_CREDENTIAL_ID",
  "public_key": "BASE64URL_DER_SPKI_P256_PUBLIC_KEY",
  "rp_id": "app.example.com",
  "origin": "https://app.example.com"
}

See Owner Accounts for the exact format rules. Read supported_owner_types from GET /v1/network before you create an agent for another owner type. EVM owners aren’t enabled by default, and agent_create with one returns owner_type_unsupported. The rest of this quickstart uses the NEAR owner.

Write the policy

The policy says what every grant on the account may do. You always send it complete, and the owner signs all of it at once. This one lets the agent:

spend only USDC on Base and USDT on NEAR, at most 25 of each per transaction
swap, transfer and withdraw, but only to the owner’s own account
spend at most 50 USD a day across all assets
run actions immediately, with no delay, schedule or approval vote

Use the JSON for cURL. For the SDK, save the TypeScript as policy.ts.

{
  "frozen": false,
  "actions": ["swap", "transfer", "withdraw"],
  "confidential": false,
  "owner_approval": false,
  "assets": [
    "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near",
    "nep141:usdt.tether-token.near"
  ],
  "limits": {
    "per_transaction": {
      "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near": "25000000",
      "nep141:usdt.tether-token.near": "25000000"
    }
  },
  "max_actions_per_hour": null,
  "destinations": {
    "mode": "only",
    "list": [
      { "action": "transfer", "address": "alice.near", "confidential": false },
      { "action": "withdraw", "chain": "near", "address": "alice.near", "memo": null }
    ]
  },
  "budget": { "daily_usd": "50", "weekly_usd": null, "monthly_usd": null },
  "timelock_ms": 0
}

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

export const USDC_BASE = "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near";
export const USDT_NEAR = "nep141:usdt.tether-token.near";

const ownerAccountId = process.env.OWNER_ACCOUNT_ID!; // alice.near

export const owner: OwnerWallet = {
  type: "near",
  account_id: ownerAccountId,
  public_key: process.env.OWNER_PUBLIC_KEY! as `ed25519:${string}`,
};

export const policy: Policy = {
  frozen: false,
  actions: ["swap", "transfer", "withdraw"],
  confidential: false,
  owner_approval: false,
  assets: [USDC_BASE, USDT_NEAR],
  limits: { per_transaction: { [USDC_BASE]: "25000000", [USDT_NEAR]: "25000000" } },
  max_actions_per_hour: null,
  destinations: {
    mode: "only",
    list: [
      { action: "transfer", address: ownerAccountId, confidential: false },
      { action: "withdraw", chain: "near", address: ownerAccountId, memo: null },
    ],
  },
  budget: { daily_usd: "50", weekly_usd: null, monthly_usd: null },
  timelock_ms: 0,
};

A new account starts with destinations: { "mode": "only", "list": [] }, which keeps funds inside the account. Funds only leave to addresses the owner lists. Deposits are always allowed. schedule is optional and left out here. See Policies & Limits for every field.

Generate the agent_create intent

Send the name, owner and policy. Add an Idempotency-Key: if the request fails and you retry with the same key, you get the same result instead of a second agent. external_user_id is optional. Set it to your own user ID to find the agent later with GET /v1/agents?external_user_id=.

curl -X POST "$NEAR_INTENTS_AGENT_API_URL/v1/generate-intent" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-agent-user-123-1" \
  -d '{
    "type": "agent_create",
    "name": "Quickstart agent",
    "external_user_id": "user-123",
    "owner": {
      "type": "near",
      "account_id": "'"$OWNER_ACCOUNT_ID"'",
      "public_key": "'"$OWNER_PUBLIC_KEY"'"
    },
    "policy": '"$(cat policy.json)"'
  }'

import { createIdempotencyKey } from "@near-intents-agent-api/sdk";
import { api } from "./agent-api.ts";
import { owner, policy } from "./policy.ts";

const generated = await api.generateIntent(
  { type: "agent_create", name: "Quickstart agent", external_user_id: "user-123", owner, policy },
  { idempotencyKey: createIdempotencyKey() },
);

// Persist generated.correlation_id and generated.agent_id under your user, and keep
// generated.idempotencyKey, before you show anything to the owner.
console.log(generated.preview.summary);

Response fields

Field	Description
`correlation_id`	Tracks this intent (`intent_…`). Persist it with your user and agent.
`agent_id`	The new agent’s ID. The agent is `PENDING` until this intent succeeds.
`status`	Always `PENDING_SIGNATURE`
`expires_at`	The owner must sign and you must submit before this time
`signer`	The owner wallet that must sign
`intent.standard`	`nep366` for NEAR owners, `eip712` for EVM, `webauthn` for passkeys
`intent.payload`	The exact payload the wallet signs
`preview`	What the owner is about to authorize. `preview.summary` is text to show before signing, and `preview.policy` is the complete policy.

Have the owner sign

Send intent and preview to your frontend. Show the owner the preview, then have their wallet sign intent.payload exactly as you received it. Don’t change, rebuild or hash it. Pick the wallet method from intent.standard:

Frontend

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

// wallet, walletClient, account and startAuthentication come from your own wallet
// integration: a NEAR wallet selector, viem and @simplewebauthn/browser. The SDK has no signers.
export async function signWithWallet(intent: GenerateIntentResponse["intent"]): Promise<SignedData> {
  switch (intent.standard) {
    case "nep366": {
      const { signedDelegateActions } = await wallet.signDelegateActions({ delegateActions: [intent.payload] });
      return { ...intent, signed_delegate: signedDelegateActions[0] };
    }
    case "nep413": {
      const nonce = Uint8Array.from(atob(intent.payload.nonce), (c) => c.charCodeAt(0));
      const { publicKey, signature } = await wallet.signMessage({ ...intent.payload, nonce });
      return { ...intent, public_key: publicKey, signature };
    }
    case "eip712":
      return { ...intent, signature: await walletClient.signTypedData({ account, ...intent.payload }) };
    case "webauthn":
      return { ...intent, credential: await startAuthentication({ optionsJSON: intent.payload }) };
  }
}

Your frontend sends the result, signed_data, back to your backend. See Owner Signing for each wallet in detail and Signing Standards for the formats.

Submit the signature

Submit the object signWithWallet returned, unchanged. For cURL, set CORRELATION_ID to the correlation_id from the generate step and SIGNED_DATA to that object as JSON.

curl -X POST "$NEAR_INTENTS_AGENT_API_URL/v1/submit-intent" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "agent_create",
    "correlation_id": "'"$CORRELATION_ID"'",
    "signed_data": '"$SIGNED_DATA"'
  }'

// 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,
});

Sending the same signature twice is safe. The API pays the gas and installs the policy.

Wait for the agent to go live

Check the status until it’s final. wait_ms=30000 makes each call wait up to 30 seconds for a change. If the status isn’t final yet, call again with the same 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"

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

const status = await settled(generated.correlation_id);
if (status.status !== "SUCCESS") throw new Error(status.failure_code ?? status.status);

const agent = await api.getAgent(generated.agent_id);
console.log(agent.status, agent.wallet?.near_account_id);

Example status

{
  "correlation_id": "intent_Zk3q9XbT7wRyL2mN8vC4dFhJ1sPaE6uGoK5iBtYxW0A",
  "agent_id": "6f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d",
  "type": "agent_create",
  "status": "SUCCESS",
  "failure_code": null,
  "created_at": "2026-10-07T11:00:00.000Z",
  "updated_at": "2026-10-07T11:00:21.000Z",
  "dispatch_committed_at": null,
  "grant": null,
  "details": {
    "agent_id": "6f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d",
    "revision": 1,
    "policy_hash": "c4a1f0e2d3b4a5968778695a4b3c2d1e0f9e8d7c6b5a49382716051f2e3d4c5b",
    "transaction_hash": "8Xq3vT9yKpL2mN4rS6uW1zB5cD7eF9gH2jK4mN6pQ8r"
  }
}

When the status is SUCCESS, the agent is ACTIVE. agent.wallet.near_account_id is the agent’s NEAR Intents account, where funds arrive. Save agent.id as AGENT_ID in .env.

Check the policy is in force

A signed policy only counts once it’s applied. Until then, actions fail with policy_not_ready.

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

const current = await api.getPolicy(generated.agent_id);
console.log(current.status, current.provider_policy_synced, current.revision);
// APPLIED, true and revision 1 mean the policy is in force.

The response also carries policy, the complete object you edit to change the rules, and usage, with each USD budget cap’s current period and the number of timelocked executions.

You now have an ACTIVE agent whose policy is in force. Save its ID in .env as AGENT_ID. That was owner signature 1 of 2.

Next: Issue a Grant

Let your backend act for the agent.

Agent API

Quickstart

Guides

Trust & Verification

API Reference

Prerequisites

Next: Issue a Grant

​Prerequisites

Next: Issue a Grant

Prerequisites