Issue a Grant

A grant says who may act for the agent. Your backend creates a secret grant token, the owner signs only its commitment, and your backend then runs agent actions with the token, with no further owner signature. A grant carries no permissions of its own. What any grant may do, where funds may go and how much is the account’s policy, which every grant on the agent shares. So:

Changing the policy never requires a new grant.
Create one grant per assistant, session or bot. An agent holds up to 50 live grants, and revoking one stops only that one.
There are no per-grant budgets. Two grants under a 50 USD daily cap share 50 USD.

Prerequisites

An ACTIVE agent from Create an Agent, with its ID saved as AGENT_ID in .env.
The signWithWallet function from that page. A NEAR owner signs grants as a message (nep413), and the same function handles it.

Create a grant token

The token is the secret that authorizes actions under this one grant. The commitment is its SHA-256 fingerprint. Store the token encrypted on your backend, next to your user and agent. It’s shown nowhere else, and the API never sees it.

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

const { token, commitment } = createGrantCredential();
// Store `token` encrypted before you go on.

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 the grant_issue intent

This grant lasts 7 days. label is up to 64 characters. It’s shown to the owner when signing and on every operation the grant authorizes. expires_at is required and at most 365 days ahead.

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: grant-user-123-assistant-1" \
  -d '{
    "type": "grant_issue",
    "agent_id": "'"$AGENT_ID"'",
    "label": "Quickstart assistant",
    "credential": "GRANT_TOKEN_COMMITMENT",
    "expires_at": "2026-10-14T12:00:00.000Z"
  }'

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

const generated = await api.generateIntent({
  type: "grant_issue",
  agent_id: process.env.AGENT_ID!,
  label: "Quickstart assistant",
  credential: commitment,
  expires_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
});

The response has the same shape as in Create an Agent. For a NEAR owner, intent.standard is nep413.

Have the owner sign and submit

Show preview.summary, have the wallet sign intent.payload as it is with signWithWallet, then submit what it returned and wait. For cURL, set CORRELATION_ID and SIGNED_DATA as in Create an Agent.

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

const status = await settled(generated.correlation_id);
if (status.type !== "grant_issue" || status.status !== "SUCCESS" || !status.details.grant)
  throw new Error(status.failure_code ?? status.status);
console.log(status.details.grant.grant_id, status.details.grant.expires_at);

When the status is SUCCESS, details.grant describes the live grant. Save the token as GRANT_TOKEN in .env. You can list an agent’s grants at any time:

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(process.env.AGENT_ID!);

Use the grant

Send the token as X-Grant-Token on agent actions. With the SDK, create one client per grant, so each assistant or bot always acts under its own grant:

TypeScript SDK

const assistant = api.forGrant(process.env.GRANT_TOKEN!);

forGrant sends the token only on the calls that need it: swap, withdraw, transfer, shield, unshield, recover and sign.To end a grant early, the owner signs a grant_revoke intent with its grant_id. Work the API had already committed to dispatch can’t be recalled. The status lists it in details.committed_correlation_ids.

You now have a live grant. Its token is in .env as GRANT_TOKEN. That was the owner’s last signature: from here on, your backend acts alone.

Next: Execute Actions

Fund the agent, quote and run a swap, then transfer and withdraw.

Agent API

Quickstart

Guides

Trust & Verification

API Reference

Prerequisites

Next: Execute Actions

​Prerequisites

Next: Execute Actions

Prerequisites