Grants

A grant says who may act for an agent: your backend creates a token (ngt_…), the owner signs for it once, and your backend sends it on every agent action. What a grantee may do is the agent’s policy, the same for every grant.

At a glance

Token: ngt_ plus 32 random bytes in base64url, created by your backend and sent as X-Grant-Token. The API never sees it at issue time and never returns it.
Commitment: the SHA-256 hex of the token. The only part the owner signs and the API stores.
Signatures: one owner signature to issue a grant, one to revoke it.
Label and expiry: 1–64 characters shown to the owner and on every action; expiry at most 365 days ahead.
Limit: 50 live grants per agent. Use one per user session, assistant or bot, so you can stop one without touching the others.

A grant token works like a password for spending within the policy. Store it encrypted on your backend. Never put it in a browser, a mobile app or a model prompt.

Issue a grant

Create the token and its commitment

Your backend makes a fresh token for every grant. Never reuse a token: the API refuses a commitment that already backs another grant (grant_credential_reused).

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

const { token, commitment } = createGrantCredential();
// Store `token` encrypted. Only `commitment` leaves your backend.

import { createHash, randomBytes } from "node:crypto";

const token = `ngt_${randomBytes(32).toString("base64url")}`;
const commitment = createHash("sha256").update(token, "utf8").digest("hex");

import base64
import hashlib
import secrets

token = "ngt_" + base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode()
commitment = hashlib.sha256(token.encode("utf-8")).hexdigest()

Generate a grant_issue intent

label, credential (the commitment) and expires_at are the grant. The agent must be ACTIVE.

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" \
  -d '{
    "type": "grant_issue",
    "agent_id": "'"$AGENT_ID"'",
    "label": "Support assistant",
    "credential": "'"$COMMITMENT"'",
    "expires_at": "2027-01-01T00:00:00Z"
  }'

const generated = await api.generateIntent({
  type: "grant_issue",
  agent_id: agentId,
  label: "Support assistant",
  credential: commitment,
  expires_at: new Date(Date.now() + 30 * 24 * 3600 * 1000).toISOString(),
});
console.log(generated.correlation_id, generated.intent.standard, generated.expires_at);

The response carries intent: { standard, payload }, a preview and the expires_at of the signing window.

The owner signs intent.payload unchanged

Your frontend has the owner’s wallet sign intent.payload with the standard in intent.standard. See Owner Signing.

Submit and wait

Send the wallet’s output back as signed_data, then follow the correlation_id.

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": "grant_issue", "correlation_id": "'"$CORRELATION_ID"'", "signed_data": '"$SIGNED_DATA"' }'

curl "$NEAR_INTENTS_AGENT_API_URL/v1/status?correlation_id=$CORRELATION_ID&wait_ms=30000" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY"

// 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: "grant_issue",
  correlation_id: generated.correlation_id,
  signed_data: signedData,
});

const status = await api.getStatus(generated.correlation_id, { waitMs: 30_000 });
if (status.type === "grant_issue" && status.status === "SUCCESS") {
  console.log(status.details.grant?.grant_id);
}

When the status is SUCCESS, details.grant holds the new grant, including its grant_id. Save the grant_id with the token: you need it to revoke the grant.

Use a grant

Send the token as X-Grant-Token on the calls that act under a grant: swap, withdraw, transfer, shield, unshield, recover and the native/… routes. Every call also sends your partner API key.

curl -X POST "$NEAR_INTENTS_AGENT_API_URL/v1/agents/$AGENT_ID/swap" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY" \
  -H "X-Grant-Token: $GRANT_TOKEN" \
  -H "Idempotency-Key: swap-user-123-1" \
  -H "Content-Type: application/json" \
  -d '{ "origin_asset": "nep141:wrap.near", "destination_asset": "nep141:usdt.tether-token.near", "amount": "1000000000000000000000000" }'

// One client per grant. It sends X-Grant-Token on the calls that need it.
const assistant = api.forGrant(token);
const swap = await assistant.swap(agentId, {
  origin_asset: "nep141:wrap.near",
  destination_asset: "nep141:usdt.tether-token.near",
  amount: "1000000000000000000000000",
});

Deposit addresses and swap quotes (swap with dry: true) need only the API key. A withdrawal preview runs under the grant, like the withdrawal. See Executions for each action.

Every status carries grant: { id, label }, the grant that authorized it. It is null for owner-signed work and for deposit addresses.
Idempotency keys are scoped to the grant. The same key under two grants is two separate actions.
A new partner API key keeps using existing grant tokens. Revoking an API key stops work that was sent through that key and has not reached its dispatch commitment.
Changing the policy never needs a new grant. Issuing or revoking a grant never changes a rule.

When a grant stops working

Cause	What you see
No token, a wrong token, an expired or a revoked grant	`agent_grant_required` (403)
The grant was issued for a different agent wallet than the one now serving the agent	`grant_wallet_mismatch` (409)
The grant, the owner’s authority or the policy changed after the action was admitted and before it ran	`authorization_stale` (409). The action did not run.

An expired grant is not renewed. Issue a new one with a new token.

List grants

GET /v1/agents/{agent_id}/grants returns every grant, including revoked and expired ones, newest first.

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

const grants = await api.listGrants(agentId);
for (const grant of grants)
  console.log(grant.grant_id, grant.label, grant.expires_at, grant.revoked_at);

Field	Description
`grant_id`	The grant’s id. Use it to revoke.
`label`	The owner-signed name
`issued_at`, `expires_at`	When the grant starts and ends
`revoked_at`, `revoked_reason`	Set once the grant is revoked, otherwise `null`
`owner_message`	The exact message the owner signed

Revoke a grant

The owner revokes one grant with a grant_revoke intent. Only that grant stops. Other grants, the policy and the funds are untouched.

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" \
  -d '{ "type": "grant_revoke", "agent_id": "'"$AGENT_ID"'", "grant_id": "'"$GRANT_ID"'" }'

const revoke = await api.generateIntent({
  type: "grant_revoke",
  agent_id: agentId,
  grant_id: grantId,
});
// 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(revoke.intent);

await api.submitIntent({
  type: "grant_revoke",
  correlation_id: revoke.correlation_id,
  signed_data: signedData,
});
const done = await api.getStatus(revoke.correlation_id, { waitMs: 30_000 });
if (done.type === "grant_revoke") console.log(done.details.committed_correlation_ids);

Sign and submit it like any owner intent. When the status is SUCCESS, details reports:

Field	Description
`grant_id`	The revoked grant
`committed_correlation_ids`	Actions that had already reached their dispatch commitment. They cannot be recalled. Follow each with `GET /v1/status`.
`committed_truncated`	`true` when more committed actions exist than the list shows. The list holds the oldest 100 that are not settled yet.

Anything that had not reached its dispatch commitment is refused: new calls with the token fail with agent_grant_required, and an action still waiting for its timelock fails with authorization_stale when it comes due. To stop a queued action while keeping the grant, the owner cancels it with an execution_cancel intent.

Lost a token? It cannot be recovered. Issue a new grant with a new token and revoke the old one.

Limits and errors

Code	Status	Meaning
`grant_limit_reached`	409	The agent already has 50 live grants. Revoke one it no longer needs.
`grant_credential_reused`	409	This token already backs another grant. Create a new token.
`grant_expiry_invalid`	409	`expires_at` is in the past, or more than 365 days ahead.
`grant_not_found`	404	The grant does not exist, or is already revoked.
`agent_not_bound`	409	The agent is not `ACTIVE` yet. Wait for its `agent_create` intent to reach `SUCCESS`.

The full list of codes is in Status & Errors.

Agent API

Quickstart

Guides

Trust & Verification

API Reference

Issue a grant

Use a grant

When a grant stops working

List grants

Revoke a grant

Limits and errors

​Issue a grant

​Use a grant

​When a grant stops working

​List grants

​Revoke a grant

​Limits and errors

Issue a grant

Use a grant

When a grant stops working

List grants

Revoke a grant

Limits and errors