Partner API Key

Your partner API key lets your backend call the Agent API. One key works for every agent your company creates. Moving an agent’s funds also needs a grant token that the agent’s owner signed for.

At a glance

Key: starts with naa_, created in the Partner Dashboard, shown once, never expires.
Header: X-API-Key on every call except the public endpoints. Agent actions add X-Grant-Token.
Where it lives: your backend only. Never in a browser, a mobile app or a model prompt.
Limits: 1,200 requests per minute per key, 3,000 per partner, 100 new agents per 24 hours.

Quick setup

Create a key

Create a partner API key in the Partner Dashboard and store it in your secret manager right away. It’s shown only once.

Set two environment variables

Every example in these docs reads them:

.env

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

The SDK uses https://api.agentsonintents.com unless you pass baseUrl.

Check the key

GET /v1/whoami answers with the key and the partner account it belongs to.

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

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,
});
console.log(await api.whoami());

const response = await fetch(`${process.env.NEAR_INTENTS_AGENT_API_URL}/v1/whoami`, {
  headers: { 'X-API-Key': process.env.NEAR_INTENTS_AGENT_API_KEY! },
});
console.log(await response.json());

import os
import requests

response = requests.get(
    f"{os.environ['NEAR_INTENTS_AGENT_API_URL']}/v1/whoami",
    headers={"X-API-Key": os.environ["NEAR_INTENTS_AGENT_API_KEY"]},
)
print(response.json())

{
  "api_key_id": "…",
  "tenant_id": "…"
}

A missing or revoked key returns 401 invalid_api_key.

What the partner API key does

The key gives your backend access to the Agent API. It tells the API which partner is calling, so it can apply your rate limits and quotas and keep your agents separate from every other partner’s.

With the key alone, you can

Create agents for any number of owners, up to your quota
Prepare owner requests and submit the owner’s signatures
Read your agents, balances, policies, grants and statuses
Get swap quotes (dry: true)
Create deposit addresses that fund an agent
Check your quotas

The key alone can't

Move an agent’s funds out. A swap, withdrawal or transfer also needs a grant token the owner signed for.
Change an agent’s policy or grants. That needs the owner’s signature.
See or touch agents that belong to another partner

All agents belong to your partner account, not to the key that created them. Any of your keys can manage any of your agents, so you can rotate keys without losing access.

Headers

Header	Value	Required on
`X-API-Key`	Your `naa_…` partner API key	Every request except the public endpoints
`X-Grant-Token`	The `ngt_…` token of one owner grant	`swap`, `withdraw` (including `dry: true` previews), `transfer`, `shield`, `unshield`, `recover` and every `native/…` route. Not needed for swap quotes, `deposit` or any read. Those need only the API key.
`Idempotency-Key`	8–128 characters of `A-Za-z0-9._:-`. One key per logical request, so a retry never runs it twice.	Required on `swap`, `withdraw` (including `dry: true` previews), `transfer`, `shield`, `unshield`, `deposit`, `recover`, `native/near/transfer` and `native/near/call`. Optional on `generate-intent`. Not needed for swap quotes.

Send JSON bodies with Content-Type: application/json. Bodies can be up to 256 KiB.

Grant tokens

Your partner API key says which partner is calling. It isn’t the owner’s permission. To run a swap, withdrawal, transfer, shield, unshield or native request, you also send the token of a grant the owner signed for that agent.

Your backend creates a random token (ngt_…) and its SHA-256 commitment.
You send only the commitment, as credential, in a grant_issue intent. Never send the token itself.
The owner signs the grant.
You send the token as X-Grant-Token on agent actions. With the SDK, api.forGrant(token) does this for you.

A grant doesn’t depend on the API key that created it, so a rotated key keeps using existing grant tokens. See Grants for creating, listing and revoking them.

Key handling

Never put your partner API key or a grant token in a browser, a mobile app or an AI model’s prompt. Your frontend talks to your backend, and only your backend talks to the Agent API.

Rotation. Create a new partner API key in the Partner Dashboard, deploy it, then revoke the old one. Agents and grant tokens keep working with the new key. Revoking a key stops any work sent through it that the API hasn’t yet committed to the wallet. Work already committed can’t be recalled.
Expiry. Partner API keys don’t expire. They stay active until you revoke them.
Number of keys. Each partner can hold up to 10 unrevoked keys by default. Revoking one frees a slot.

Limits and quotas

By default, each key gets 1,200 requests per minute and your partner account 3,000. You can create 100 agents per rolling 24 hours and 100 deposit addresses per agent per rolling 24 hours, hold 10 unrevoked keys, and change each agent’s policy once per 10 minutes. Over a limit, the API answers 429 with a Retry-After header. Read your own limits with GET /v1/quotas. See Network & Quotas for every limit and how to retry a 429.

Public endpoints

These endpoints need no key:

Endpoint	Returns
`GET /v1/tokens`	Every asset agents can hold and trade: `asset_id` (the value executions take), `symbol`, `decimals`, `blockchain` and a USD `price`. `price` is `null` when it isn’t current, never zero.
`GET /v1/network`	The network, the owner types this deployment accepts (`supported_owner_types`: `near` and `passkey` by default, as EVM isn’t enabled by default) and live dependency status
`GET /openapi.json`	The OpenAPI 3.1 document
`GET /llms.txt`	A plain-text guide for AI models that call the API directly

See Network & Quotas for what GET /v1/network reports.

Common errors

Code	Status	What to do
`invalid_api_key`	401	Send a live `naa_…` key in `X-API-Key`
`rate_limited`	429	Wait for `Retry-After`, then retry
`agent_grant_required`	403	Send `X-Grant-Token` with the token of a live grant on this agent
`idempotency_key_required`	400	Send an `Idempotency-Key` that’s stable for this logical request
`idempotency_conflict`	409	This key was used with a different body. Reuse the original body, or use a new key for a new request.
`grant_credential_reused`	409	Create a new grant token for every grant
`grant_limit_reached`	409	The agent already has 50 live grants. Revoke one.

See Status & Errors for every error code.

Agent API

Quickstart

Guides

Trust & Verification

API Reference

Quick setup

What the partner API key does

With the key alone, you can

The key alone can't

Headers

Grant tokens

Key handling

Limits and quotas

Public endpoints

Common errors

​Quick setup

​What the partner API key does

With the key alone, you can

The key alone can't

​Headers

​Grant tokens

​Key handling

​Limits and quotas

​Public endpoints

​Common errors

Quick setup

What the partner API key does

Headers

Grant tokens

Key handling

Limits and quotas

Public endpoints

Common errors