Network & Quotas

Three small endpoints tell you what the API is doing right now and what you may do next. Read them before you act, or after a retryable error.

Endpoint	Auth	Returns
`GET /v1/network`	none	The network, supported owner types and the health of the services behind the API
`GET /v1/quotas`	API key	Your effective limits and current usage
`GET /v1/whoami`	API key	The API key and partner account making the call

Network status

GET /v1/network is public and cheap: it reads cached results of background probes that run about once a minute, and it never calls a provider on your behalf.

curl "$NEAR_INTENTS_AGENT_API_URL/v1/network"

const network = await api.getNetwork();
console.log(network.status.overall);
for (const component of network.status.components)
  console.log(component.id, component.status, component.reason, component.affects);

{
  "network": "mainnet",
  "contract_id": "outlayer.near",
  "supported_owner_types": ["near", "passkey"],
  "status": {
    "overall": "operational",
    "checked_at": "2026-10-07T17:14:01.866Z",
    "components": [
      { "id": "one_click", "status": "operational", "reason": null, "affects": ["swap", "limit_order", "withdraw", "deposit"], "since": "2026-10-07T16:42:02.129Z", "checked_at": "2026-10-07T17:14:02.147Z" },
      { "id": "custody", "status": "operational", "reason": null, "affects": ["swap", "limit_order", "withdraw", "transfer", "shield", "unshield", "deposit", "owner_intents", "balances"], "since": "2026-10-07T16:42:01.882Z", "checked_at": "2026-10-07T17:14:01.866Z" },
      { "id": "near", "status": "operational", "reason": null, "affects": ["owner_intents", "balances"], "since": "2026-10-07T16:42:01.866Z", "checked_at": "2026-10-07T17:14:02.017Z" }
    ]
  }
}

Field	Description
`network`	The network this API serves: `mainnet`
`supported_owner_types`	The owner types `agent_create` accepts. By default `near` and `passkey`. `evm` appears only on deployments that enable it. Existing EVM-owned agents keep working either way. Any other owner type fails with `owner_type_unsupported`.
`status.overall`	The worst component status: `down`, then `degraded`, then `unknown`, then `operational`
`status.components[]`	One entry per dependency

Each component has an id, a status (operational, degraded, down or unknown), a short snake_case reason (null when operational), the actions it affects, since (when it entered this status) and checked_at.

Component	What it is	Affects	Reasons
`one_click`	Quotes and routing on NEAR Intents 1Click. A real dry quote is the probe.	`swap`, `limit_order`, `withdraw`, `deposit`	`quote_failing`, `quote_rejected`, `quote_rate_limited`, `quote_slow`
`custody`	The agent wallet service, including the API’s own circuit breaker for it	Every execution, `owner_intents` and `balances`	`breaker_open`, `health_failing`, `recovering`
`near`	The NEAR network, judged by the age of its latest block and by the `intents.near` contract read that public balances use	`owner_intents` (generate and submit-intent) and `balances`	`rpc_unreachable`, `block_stale`, `view_failing`, `block_delayed`, `rpc_syncing`

A probe that times out or errors reports probe_failed. One failed probe reads degraded. Two in a row read down. Every component is unknown until its first probe.

The status is advisory. The API never refuses a request because of it, so an action can succeed while a component reads down, and fail while it reads operational. Read it after route_unavailable or provider_unavailable. If a component your action depends on is down, wait and retry later instead of changing the request. After a provider_unavailable that is a recorded execution outcome (no meta.retryable), check one_click and send the work again under a new Idempotency-Key once it reports operational.

Quotas

GET /v1/quotas shows your limits and what you have used.

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

const quota = await api.getPartnerQuota();
console.log(quota.limits, quota.usage);

{
  "revision": 0,
  "overrides": {},
  "limits": { "daily_agents": 100, "requests_per_minute": 4000, "key_requests_per_minute": 1500 },
  "usage": { "agents_last_24_hours": 3, "requests_this_minute": 14 },
  "observed_at": "2026-10-07T17:14:01.866Z"
}

overrides lists limits the operator changed for your account, and revision counts those changes. limits is what applies to you now. The numbers above are the defaults. Always read your own. limits and usage cover only agents created per day and the two request rates. The deposit, grant, wait and cooldown limits in the table below are not in the response.

Limits

Limit	Default	Over the limit
Requests per minute, per partner account	4,000	`rate_limited` (429)
Requests per minute, per API key	1,500	`rate_limited` (429)
Agents created per rolling 24 hours, across all keys	100	`agent_creation_quota_exceeded` (429). A failed or deleted agent does not refund its slot.
Deposit addresses per agent per rolling 24 hours, across all keys	100	`deposit_quota_exceeded` (429)
Live API keys	10	The partner portal refuses another key until you revoke one. The Agent API does not enforce or report this limit.
Live grants per agent	50	`grant_limit_reached` (409)
Concurrent `wait_ms` status waits per API key	10	The extra reads answer at once, as plain reads without waiting
Ordinary policy changes per agent	One per 10 minutes	`policy_change_throttled` (429)
Unfreezes per agent	One per 10 minutes	`agent_unfreeze_throttled` (429)
Custody operations per agent wallet per rolling 24 hours: transfers, swaps, limit-order placements and cancels, withdrawals, confidential moves and withdrawal previews (`dry`); quotes, limit-order previews and reads don’t count	1,000, set by the custody provider	`provider_limit_reached` (429)

The partner-account request limit, the agent limit and the deposit limit are shared by all of your keys, so creating more keys never raises them. Request limits apply to every call that needs an API key. GET /v1/network and GET /v1/tokens need none. Every attempt counts against its key, refused ones too. Only an attempt within the key’s own allowance counts against the partner account, so a key that is over its limit cannot use up the partner’s.

`GET /v1/whoami`

Checks that a key works and says which partner account it belongs to.

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

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

HTTP 429

A 429 means “later”. These codes carry the time to retry:

Code	Cause
`rate_limited`	The request rate for your key or partner account. The per-address limit at the edge also answers `rate_limited`, see below.
`agent_creation_quota_exceeded`	The daily agent limit
`deposit_quota_exceeded`	The agent’s daily deposit address limit
`policy_change_throttled`	The 10-minute policy cooldown
`agent_unfreeze_throttled`	The 10-minute unfreeze cooldown
`provider_limit_reached`	The custody provider’s daily operation quota for the agent wallet. The provider normally says when it frees up; if it does not, the response carries neither `available_at` nor `meta.retryable`. An execution’s refusal is recorded, so it carries `available_at` and `Retry-After` but not `meta.retryable`: send the work again under a new key.

Each of them returns:

errors[0].meta.retryable: true
errors[0].meta.available_at, an ISO 8601 time when the limit frees up
a Retry-After header with the wait in whole seconds

The edge also caps each client IP address per 10 seconds, before a request reaches the API. It answers rate_limited (429) with Retry-After: 10 and errors[0].meta.retryable: true, but no meta.available_at. Retry after 10 seconds. provider_rate_limited is also a 429, but it comes from a service behind the API. It has no available_at, and it always carries Retry-After: 10. Nothing was sent. With meta.retryable true, repeat the same request after the wait, under the same Idempotency-Key where the request took one. Without it, the refusal is recorded as the operation’s outcome, so send the work again under a new key after the wait.

import { AgentApiError } from "@near-intents-agent-api/sdk";

async function retryRead<T>(run: () => Promise<T>): Promise<T> {
  try {
    return await run();
  } catch (error) {
    if (!(error instanceof AgentApiError) || error.status !== 429) throw error;
    // availableAt is missing on the per-address limit: fall back to its Retry-After
    // (retryAfterSeconds, SDK 0.7.2), then to the 10 seconds that limit asks for.
    const waitMs = error.availableAt
      ? Date.parse(error.availableAt) - Date.now()
      : (error.retryAfterSeconds ?? 10) * 1000;
    await new Promise((resolve) => setTimeout(resolve, Math.max(0, waitMs)));
    return run();
  }
}

const policy = await retryRead(() => api.getPolicy(agentId));

Retry a 429 on a write with the same Idempotency-Key and the same body. Never switch to a new key to get past a limit, because a request the API already accepted would run twice. A refusal recorded for an action is replayed under its key, so for those, see Status & Errors.

Agent API

Quickstart

Guides

Trust & Verification

API Reference

Network status

Quotas

Limits

`GET /v1/whoami`

HTTP 429

Next steps

Status & Errors

Executions