---
title: "Update an Account"
method: PUT
path: "/v0/accounts/{accountId}"
tags: ["Accounts"]
---

# Update an Account

`PUT /v0/accounts/{accountId}`

<Callout intent="warning">
  The endpoints exposed here are currently in **Beta**! As we continue to build our initial offering, these endpoints may implement breaking changes. Be sure to check back for our change log regularly as a precaution.
</Callout>

Apply a single change to an existing account, selected by `operation`:

- **`setName`**: rename a wallet or bank account (send `name`).
- **`addNetwork`**: register an existing wallet on an additional `network`, which starts a new `mint` entitlement there (see [Wallet entitlements](/api/endpoints/accounts/overview#wallet-entitlements)). Rejected with `409` if the address is already registered there.
- **`requestEntitlement`**: request an `entitlement` (currently `instant_settlement`) on an existing wallet `network`. Returns `400` if the entitlement isn't requestable for that network. See [Wallet entitlements](/api/endpoints/accounts/overview#wallet-entitlements) for how requests are reviewed and approved.

The response is the full updated account, same shape as `GET /v0/accounts`.

## Path parameters

- `accountId` string, uuid, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `operation` 'setName' | 'addNetwork' | 'requestEntitlement', required
  - `name` string — User-set label. Free-form; max 200 characters.
  - `network` 'arbitrum' | 'avalanche' | 'base' | 'binance-smart-chain' | 'core' | 'ethereum' | 'fraxtal' | 'gnosis' | 'immutable' | 'injective' | 'katana' | 'mantle' | 'monad' | 'plume' | 'polygon-pos' | 'solana' | 'sui'
  - `entitlement` 'instant_settlement' — Entitlement to request. Moves to pending_approval; granting stays Agora-side.

## Response `200`

OK

- union
  - AccountsUpdateResponse2000 — Customer-owned blockchain address (CustomerAddress).
    - `id` string, uuid, required — Stable UUID identifying this account; safe to cache or display.
    - `address` string, required — On-chain address. EIP-55 checksummed for EVM (`ethereum`), base58 for Solana.
    - `addressFormat` 'ethereum' | 'solana', required — Address syntax family. `ethereum` covers every EVM chain (Ethereum, Base, Polygon, Arbitrum, etc.); per-chain authorization is enforced separately via the account's chain entitlements.
    - `createdAt` string, date-time, required — ISO-8601 UTC timestamp when this address was added to the org.
    - `kind` 'wallet', required — Discriminator: this is a customer-owned blockchain address.
    - `name` string, required — User-set label. Free-form; may be empty if the user hasn't set one.
    - `networks` V0AccountsAccountIdPutResponsesContentApplicationJsonSchemaOneOf0NetworksItems[], required — The networks this address is registered on, each with its per-type entitlement states.
      - `chain` 'arbitrum' | 'avalanche' | 'base' | 'binance-smart-chain' | 'core' | 'ethereum' | 'fraxtal' | 'gnosis' | 'immutable' | 'injective' | 'katana' | 'mantle' | 'monad' | 'plume' | 'polygon-pos' | 'solana' | 'sui', required — Network the wallet is registered on (kebab-case public network id).
      - `entitlements` V0AccountsAccountIdPutResponsesContentApplicationJsonSchemaOneOf0NetworksItemsEntitlementsItems[], required — Entitlement states on this network, one per type the wallet holds on the chain.
        - `type` 'instant_settlement' | 'mint' | 'rewards', required — Entitlement type. `mint` is the mint capability gated by the per-chain compliance scan; `instant_settlement` is the instant-settlement whitelist; `rewards` is rewards eligibility.
        - `status` 'approved' | 'conditionally_approved' | 'pending_approval' | 'pending_removal' | 'rejected' | 'removed', required — Entitlement status. `pending_approval` is requested and under Agora review; `approved` is active. `conditionally_approved` applies to `mint` only: the address is usable now (screening and whitelisting are auto-initiated) while final approval is still pending internally. `instant_settlement` and `rewards` stay `pending_approval` until reviewed. The API never auto-approves.
  - AccountsUpdateResponse2001 — Customer-owned bank account (WireDetail, status=verified).
    - `id` string, uuid, required — Stable UUID identifying this account; safe to cache or display.
    - `accountNumber` string, required — Full bank account number.
    - `bankName` string, required — Name of the receiving bank.
    - `beneficiary` string, required — Account-holder name on the wire. Part of the account's identity: distinguishes accounts that share a routing + account number (e.g. omnibus/custodian accounts holding several funds under one account number).
    - `createdAt` string, date-time, required — ISO-8601 UTC timestamp when this account was added to the org.
    - `currency` 'usd', required — Settlement currency. Today only `usd`; will extend as new currencies launch.
    - `kind` 'bank', required — Discriminator: this is a customer-owned bank account.
    - `name` string, required — User-set label. Free-form; may be empty if the user hasn't set one.
    - `routingNumber` string, required — ABA routing number identifying the receiving bank. A public bank identifier, returned in full.

## Other responses

- `400` — This entitlement cannot be requested in its current state.
- `401` — Authentication is required.
- `403` — The account is not eligible for the requested route direction.
- `404` — Account not found.
- `409` — An account with these details already exists.
- `429` — Too many requests.
- `500` — An unexpected error occurred.

---

[API](https://skmtc.net/agora/apis/endpoints.md) · [All operations](https://skmtc.net/agora/apis/endpoints/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agora/endpoints/versions/8525bfff7634/schema)