---
title: "Link a wallet to the authenticated entity"
method: POST
path: "/api/v1/wallets"
tags: ["Wallets"]
---

# Link a wallet to the authenticated entity

`POST /api/v1/wallets`

## Request

- Base URL: `https://www.agenttax.io`
- URL: `https://www.agenttax.io/api/v1/wallets`
- Auth: HTTP bearer

Records that the calling entity owns the supplied wallet. Future x402 payments from this wallet to /calculate or /trades will auto-log against the entity. **Session auth only** — API keys are rejected with 403 SESSION_AUTH_REQUIRED until ECDSA signed-message proof ships in V2.

## Request body

- LinkWalletRequest
  - `wallet_address` string, required: 0x-prefixed 40-char hex (Ethereum / Base address).
  - `label` string, nullable
  - `chain` string: Chain identifier (default "base").

## Response `201`

Wallet linked.

## Other responses

- `400`: Validation failure
- `401`: Authentication required.
- `403`: Session auth required (API key rejected for wallet writes).
- `409`: Wallet already linked to a different entity.

---

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