---
title: "Set agent default wallet"
method: POST
path: "/wallets/{walletId}/agents/{agentId}/default"
tags: ["Wallets"]
---

# Set agent default wallet

`POST /wallets/{walletId}/agents/{agentId}/default`

Make this wallet the default for the attached agent. For a connected agent, the default applies only to this customer connection and also requires delegations.update. Omitted walletId calls use this default. Agent credentials and delegated callers cannot change it.

## Path parameters

- `walletId` string, required — Wallet ID (wal_*).
- `agentId` string, required — Agent ID (agt_*).

## Headers

- `Idempotency-Key` string, required
- `X-Instance-ID` string, nullable

## Response `200`

Successful Response

- object
  - `data` object, required
    - `type` 'agent', required — Resource type. Always `agent`.
    - `id` string, required — Agent ID (agt_*).
    - `attributes` object, required
      - `name` string, required — Agent display name.
      - `description` string, nullable, required — Agent description. Null for connected agents.
      - `tags` object, required — Agent tags. Empty for connected agents.
      - `handle` string, nullable, required — Agent handle, such as @acme-support, or null when none is set.
      - `status` 'ACTIVE' | 'REVOKED', required — Agent status: ACTIVE, or REVOKED after deletion.
      - `limits` object, nullable, required — Agent limits for an owned agent, or this customer's connection limits for a connected agent.
        - `perTransaction` integer, nullable — Per-transaction spending limit in cents, or null for no limit.
        - `perDay` integer, nullable — Daily spending limit in cents, or null for no limit.
        - `perMonth` integer, nullable — Monthly spending limit in cents, or null for no limit.
      - `createdAt` string, date-time, nullable, required — When the agent was created. Null for connected agents.
      - `createdBy` string, nullable, required — User who created the agent. Null for connected agents.
      - `lastActiveAt` string, date-time, nullable, required — When the agent last authenticated. Null for connected agents.
    - `relationships` object, required
      - `party` object, required — Party that owns the agent.
        - `data` object, required — Related resource identifier.
          - `type` 'party', required — Resource type. Always `party`.
          - `id` string, required
    - `meta` object, required
      - `walletAccess` object, required — The agent's access to this wallet.
        - `accessType` 'owned' | 'connected' — Whether the wallet owner owns the agent or has an active customer connection to it.
        - `isDefault` boolean, required — Whether this is the agent's default wallet.
        - `attachedAt` string, date-time, required — RFC 3339 timestamp when the agent was attached to this wallet.

## Other responses

- `400` — Validation Error
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
- `409` — Conflict
- `422` — Validation Error. The response contains one error object for each invalid request value.
- `428` — Precondition Required
- `429` — Too Many Requests
- `500` — Internal Server Error
- `501` — Not Implemented
- `502` — Bad Gateway
- `503` — Service Unavailable

## Changes

- **2026-09-26** `ca3882d75a00` — 1 info
  - added the optional property `data/meta/walletAccess/accessType` to the response with the `200` status
- **2026-09-02** `c7c12da5915f` — 12 info
  - added the optional property `errors/items/meta/limitScope` to the response with the `400` status
  - added the optional property `errors/items/meta/limitScope` to the response with the `401` status
  - added the optional property `errors/items/meta/limitScope` to the response with the `403` status
  - added the optional property `errors/items/meta/limitScope` to the response with the `404` status
  - …8 more
- **2026-08-27** `359d267dca88` — 1 info
  - deleted the `header` request parameter `X-Agent-ID` with deprecation
- **2026-08-23** `b1ad79e918ac` — 1 info
  - `header` request parameter `X-Agent-ID` was deprecated
- **2026-08-13** `ba1fb54c5939` — 1 info
  - added the required property `data/attributes/tags` to the response with the `200` status

[Full history](https://skmtc.dev/natural/apis/natural-api/changes/wallets/:walletId/agents/:agentId/default/post.md)

---

[API](https://skmtc.dev/natural/apis/natural-api.md) · [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) · [OpenAPI document](https://skmtc.dev/natural/apis/natural-api/revisions/acc8f2f3d25e?raw)