Funding an Agent

An agent’s account is its confidential balance on NEAR Intents. Fund it from any supported chain with a one-time deposit address. Some agents also hold a legacy public balance. It can only be emptied: shield moves it to the confidential balance, and a withdrawal with confidential: false pays it out. See Shield and the legacy public balance.

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: needs a grant and confidential: true in the policy. unshield is always refused with public_balance_exit_only.
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	Default `true`: the address credits the confidential balance. `false` is refused with `public_balance_exit_only` (400).

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.
`details.deposit_seen_at`	Optional. When the API first saw funds behind the address, or the deposit processing. Absent until then. It is kept from the first sighting.

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.

A payment into an address that already ended FAILED with deposit_expired reopens the deposit: the API drops deposit_expired, and the status follows 1Click again to SUCCESS or REFUNDED. Check the result with the agent’s balance:

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

const { balances } = await api.getBalances(agentId); // the confidential balance
for (const balance of balances) console.log(balance.symbol, balance.balance, balance.balance_raw);

source defaults to confidential. Use source=public to read the legacy public 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 passes the API’s balance check, is recorded and dispatched, and then fails at the provider. Wait for balance_raw to drop before you spend what remains. 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 that the deposit targeted. A payment that lands on an address after it ended FAILED with deposit_expired reopens the deposit, and 1Click settles or refunds it like any other. A refund goes to details.refund_to and 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 the legacy public balance

shield moves the legacy public balance to the confidential balance. It moves funds between the agent’s own balances, so it needs no destination. It does need a grant, and the policy must have confidential: true. unshield, which moved funds back to the public balance, is always refused: every request gets public_balance_exit_only (400), whatever its body. Unshields recorded earlier still read and settle. To empty a public balance without shielding it, withdraw from it with confidential: false. See Executions.

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",
});

Check	Applies to shield
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
`public_balance_exit_only`	400	`confidential: false` on the deposit, or any `unshield` request. Nothing was created.
`wallet_frozen`	409	The owner froze the agent. No deposit address is created until it is unfrozen.
`policy_action_denied`	403	(shield, deposit) The policy has `confidential: false`. A stored policy can still have it off, and shielding needs an owner-signed `policy_update` that turns it on.
`policy_transaction_limit_exceeded`, `policy_limit_exceeded`, `policy_action_limit_exceeded`	403	(shield) The amount or the hourly action count passes the owner’s per-asset limits. Shield counts toward them like any other action.
`policy_denied`	409	(shield) The wallet provider’s policy refuses the request
`insufficient_balance`	400, 409	(shield) 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 the legacy public balance

Quotas

Errors