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: an opaque string, created in the partner portal, shown once, expires 365 days after creation.
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,500 requests per minute per key, 4,000 per partner, 100 new agents per 24 hours.

Quick setup

Create a key

Create a partner API key in the partner portal 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=<your partner API key>
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, unknown or revoked key returns 401 invalid_api_key. A key created before the partner portal returns 401 api_key_retired: create a new one in the portal.

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 and limit-order previews (dry: true)
Read an agent’s limit orders
Create deposit addresses that fund an agent
Check your quotas

The key alone can't

Move an agent’s funds out. A swap, limit order, 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 partner API key	Every request except the public endpoints
`X-Grant-Token`	The `ngt_…` token of one owner grant	`swap`, `limit-orders` (placing an order, `…/cancel` and `…/cancel-all`), `withdraw` (including `dry: true` previews), `transfer`, `shield`, `recover` and every `native/…` route. Not needed for swap quotes, limit-order previews, `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`, a live `limit-orders` placement, `withdraw` (including `dry: true` previews), `transfer`, `shield`, `deposit`, `recover`, `native/near/transfer` and `native/near/call`. Optional on `generate-intent`. Not needed for swap quotes, limit-order previews or limit-order cancels.

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, limit order, withdrawal, transfer, shield 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.

Opaque. Treat the key as an opaque string. Don’t check its prefix or format, and don’t parse it.
Where keys come from. You create, list and revoke keys in the partner portal. The Agent API has no key endpoints. The portal shows a key once, so store it right away.
Rotation. Create a new key in the portal, switch your backend to it, then revoke the old one in the portal. 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.
Revocation timing. A revoked key stops new dispatches at once and every other request within 30 seconds.
Expiry. A key expires 365 days after you create it. Create its replacement before then.
Number of keys. The portal allows up to 10 live keys per partner. Revoking one frees a slot.
Portal outage. While the portal is down, a key keeps the last answer the portal gave for it, so a revocation made during the outage may not apply until the portal is back. A key the portal never answered for gets 503 key_verification_unavailable: send the same request again later.
Retired keys. Keys created before the partner portal no longer work. They get 401 api_key_retired, which is not retryable. Create a new key in the portal.

Limits and quotas

By default, each key gets 1,500 requests per minute and your partner account 4,000. You can create 100 agents per rolling 24 hours and 100 deposit addresses per agent per rolling 24 hours, hold 10 live 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 key from the partner portal in `X-API-Key`. A revoked, expired or unknown key gets this code.
`api_key_retired`	401	The key was created before the partner portal. Create a new key in the portal. Not retryable.
`key_verification_unavailable`	503	The portal could not confirm the key. Send the same request again later.
`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