---
title: "Grant agent access to wallet"
method: POST
path: "/wallets/{walletId}/agents"
tags: ["Wallets"]
---

# Grant agent access to wallet

`POST /wallets/{walletId}/agents`

Grant an owned or customer-connected agent access to a standard wallet. Customer connections also require delegations.update. The first wallet becomes the default; adding another preserves the existing default. Agent credentials and delegated callers cannot manage wallet access.

## Path parameters

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

## Headers

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

## Request body

- object
  - `data` object, required
    - `attributes` object, required
      - `agentId` string, required — Owned agent or active customer-connected agent (agt_*) to grant access to.

## 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/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/ca3882d75a00?raw)