Funding an Agent

An agent holds two balances on NEAR Intents: a public balance and a confidential balance. Fund either one from any supported chain with a one-time deposit address, then move funds between them with shield and unshield.

At a glance

Deposit address: POST /v1/agents/{agent_id}/deposit with your API key and an Idempotency-Key. No grant, no owner signature, never spends the agent’s funds.
Refunds: always to the agent’s own balance. There’s no refund address to choose.
Shield and unshield: need a grant and confidential: true in the policy.
Limit: 100 deposit addresses per agent per rolling 24 hours.

Create a deposit address

A deposit address needs your partner API key and an Idempotency-Key. It needs no grant and no owner signature, and the policy’s destinations, USD budget, timelock and schedule do not apply. It never spends the agent’s funds.

curl -X POST "$NEAR_INTENTS_AGENT_API_URL/v1/agents/$AGENT_ID/deposit" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY" \
  -H "Idempotency-Key: deposit-user-123-1" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_asset": "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near"
  }'

const deposit = await api.deposit(
  agentId,
  { origin_asset: "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near" },
  { idempotencyKey: "deposit-user-123-1" },
);
const { details } = deposit;
console.log(deposit.status, details.deposit_address, details.memo, details.min_amount, details.expires_at);

Request

Field	Required	Description
`origin_asset`	Yes	The exact `asset_id` from `GET /v1/tokens` of the token the sender holds. It fixes both the chain and the token.
`amount`	No	An exact deposit, in atomic units of `origin_asset`. Leave it out to accept any amount at or above `details.min_amount`.
`destination_asset`	No	The asset credited to the agent, when it differs from `origin_asset`. The deposit is converted on arrival.
`confidential`	No	`true` credits the confidential balance instead of the public one. Default `false`.

Response

The status is PENDING_DEPOSIT until funds arrive.

Field	Description
`details.deposit_address`	The only place to send funds. If it is missing, send nothing.
`details.memo`	Send it with the deposit on chains that require one
`details.min_amount`	The smallest deposit that is credited, in atomic units of `origin_asset`. With an exact `amount`, it equals that amount.
`details.expires_at`	When the quote ends. An address nothing was paid into stays open for one more day, then ends `FAILED` with `deposit_expired`.
`details.refund_to`	The agent’s own NEAR Intents account. Every refund goes here.

The correlation_id (op_…) is a tracking id. It is never an address. Send funds only to details.deposit_address.

Without amount, the address stays open for 3 days and credits any payment at or above min_amount. With an amount, it is quoted for exactly that amount for about a day. details.expires_at is always the authoritative deadline.

Follow the deposit

Send the funds to the address, then follow the correlation_id with GET /v1/status.

Status	Meaning
`PENDING_DEPOSIT`	Waiting for funds
`PROCESSING`	Funds arrived and are being credited
`SUCCESS`	Credited to the agent’s balance. Final.
`REFUNDED`	The deposit could not be credited and was returned to `details.refund_to`. Final.
`FAILED`	The deposit did not complete. `failure_code` says why. Final. An address still unpaid one day after `details.expires_at` ends `FAILED` with `deposit_expired`. A deposit with a known deposit transaction or amount never expires: it stays open until 1Click settles or refunds it. A deposit that has no `details.deposit_address` ten minutes after it was created never gets one and ends `FAILED` with `deposit_address_missing`. Nothing can have been paid into it.

Check the result with the agent’s balance:

curl "$NEAR_INTENTS_AGENT_API_URL/v1/agents/$AGENT_ID/balances?source=public" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY"

const { balances } = await api.getBalances(agentId, { source: "public" });
for (const balance of balances) console.log(balance.symbol, balance.balance, balance.balance_raw);

Use source=confidential for the confidential balance. balance_raw is the exact atomic amount for arithmetic. balance is the exact decimal amount for display, or null when the token’s decimals are unknown. Use balance_raw then. available_raw and available are the same two formats for what a new request can still spend: the balance less queued or timelocked work that has not been dispatched yet. Dispatched work leaves the balance when the provider’s balance reflects it, a few seconds after dispatch; a request for all of available_raw sent in that window is refused once it does. Read available instead of working it out yourself.

Refunds

There is no refund address to choose. A wrong amount, a late payment or a failed conversion refunds into the agent’s own balance, in the same balance type (public or confidential) that the deposit targeted. A payment that lands on an address after it ended FAILED with deposit_expired is refunded to details.refund_to too. The refund shows up as REFUNDED with details.refund_tx_hash.

Retries and keys

One key makes one address. Retrying with the same key returns the same operation. A new key creates a new address.
Save the key before you send the request. If the connection drops, reuse it.
An address creation is never replayed automatically after a lost provider response, and a deposit cannot be revived with recover. Only use an address that a successful response returned.

Other ways to fund an agent

From another NEAR Intents account: send a transfer to agent.wallet.near_account_id, from any NEAR Intents account.
From another agent: use transfer under a grant, subject to the policy’s destinations.

Shield and unshield

shield moves a public balance to the confidential balance. unshield moves it back. Both move funds between the agent’s own balances, so they need no destination. They do need a grant, and the policy must have confidential: true.

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

const assistant = api.forGrant(grantToken);
const shielded = await assistant.shield(agentId, {
  asset: "nep141:usdt.tether-token.near",
  amount: "5000000",
});
const back = await assistant.unshield(agentId, {
  asset: "nep141:usdt.tether-token.near",
  amount: "5000000",
});

Check	Applies to shield and unshield
Grant	Required
Policy	`confidential: true`
Destination rule	Not applicable. The funds stay in the agent’s own account.
USD budget	Not counted
Timelock and schedule	Yes. See Executions.
Owner approval	Yes, when `owner_approval` is on. See Owner approval.

Moving funds between the two balances does not refund earlier USD budget usage.

Quotas

Each agent can be issued at most 100 deposit addresses per rolling 24 hours, whichever of your keys asks; other agents are not affected. Over that, the API answers deposit_quota_exceeded (HTTP 429) with errors[0].meta.available_at, the time the oldest address leaves the window, and a Retry-After header. See Network & Quotas.

Errors

Code	Status	Meaning
`unsupported_token`	400	`origin_asset` or `destination_asset` is not in `GET /v1/tokens`
`amount_too_low`	400	`amount` is below the route’s minimum. Leave `amount` out, or send at least `meta.min_amount` (atomic units of `origin_asset`) when it is present.
`route_unavailable`	400	No route for this pair right now. Nothing was created.
`provider_refused`	400	The quote service refused these terms for the reason in `detail`. Nothing was created; repeating will not help. Change the request and use a new key.
`provider_unavailable`	503	The quote service did not answer. Nothing was created. Check `GET /v1/network` and try again.
`deposit_quota_exceeded`	429	This agent’s daily limit of deposit addresses. Retry at `meta.available_at`.
`invalid_address`	400	The provider refused an address for this route
`wallet_frozen`	409	The owner froze the agent. No deposit address is created until it is unfrozen.
`policy_action_denied`	403	(shield, unshield) The policy has `confidential: false`
`policy_limit_exceeded`, `policy_action_limit_exceeded`	403	(shield, unshield) The amount or the hourly action count passes the owner’s per-asset limits. Shield and unshield count toward them like any other action.
`policy_denied`	409	(shield, unshield) The wallet provider’s policy refuses the request
`insufficient_balance`	400, 409	(shield, unshield) The balance does not cover the amount. `meta.available_amount` is what it can still spend.

See Status & Errors for every code.

Agent API

Quickstart

Guides

Trust & Verification

API Reference

Create a deposit address

Request

Response

Follow the deposit

Refunds

Retries and keys

Other ways to fund an agent

Shield and unshield

Quotas

Errors

​Create a deposit address

​Request

​Response

​Follow the deposit

​Refunds

​Retries and keys

​Other ways to fund an agent

​Shield and unshield

​Quotas

​Errors

Create a deposit address

Request

Response

Follow the deposit

Refunds

Retries and keys

Other ways to fund an agent

Shield and unshield

Quotas

Errors