# Add an Address Book Entry

A new entry, cooling from its request: one of your wallets, someone else's address, or a contract.

## Overview

- **By `kind`**: `internal` takes `walletId` and nothing of the address; `external` takes `family`, `network`, `address` and optionally `chain`; `contract` takes `network`, `chain` and `address`, and its code is checked on that chain. The rules of each field: [Entries](https://docs.aureahub.com/docs/guide-address-book.md).
- **`201` with the entry**, `version` `1`, `status` `cooling` until `activeAt` — your cooling period from now (`coolingPeriodSeconds`) —, or `active` at once when that period is 0. There is no approval step: `approval.approvedBy` is `null` and `approval.requiredApprovals` `0` ([No Approval Step](https://docs.aureahub.com/docs/guide-address-book.md)).
- **An external address your settings require to be proven** is `pending_approval` instead, with `approval` `null`: its owner proves it ([Prove Ownership](https://docs.aureahub.com/docs/address-book-proof-verify.md)), and the proof starts its cooling.
- The body is checked as sent: a field that doesn't belong — or one the kind doesn't take — answers `400` `ADDRESS_BOOK_REQUEST_INVALID` with each problem in `details.errors`.
- Other refusals: `400` `ADDRESS_BOOK_WALLET_NOT_FOUND`, `ADDRESS_BOOK_ACCOUNT_NOT_FOUND`, `ADDRESS_BOOK_CHAIN_UNKNOWN`, `ADDRESS_BOOK_ADDRESS_CHECKSUM_INVALID`, `ADDRESS_BOOK_ADDRESS_INVALID`; `409` `ADDRESS_BOOK_ENTRY_EXISTS`; for a contract, `422` `ADDRESS_BOOK_ADDRESS_NOT_A_CONTRACT` and `503` `ADDRESS_BOOK_CONTRACT_UNVERIFIED` — [Refusals](https://docs.aureahub.com/docs/guide-address-book.md).
- For `owner`, `tenantadmin`, `non_signing_admin` and `editor`.

## Endpoint

### `POST /v1/address-book/entries`

Authentication: bearer token required.

Adds an entry to your tenant's address book: it cools from this request.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | yes | `internal`, `external` or `contract` |
| `label` | string | yes | 1–100 characters, no space at either end |
| `tags` | string[] | no | Up to 20, each named once: 1–50 of `A–Z a–z 0–9 _ . : -`, starting with a letter or a digit |
| `customerRefId` | string \| null | no | Your reference for the counterparty: 1–128 of `A–Z a–z 0–9 _ . : @ / + -`, starting with a letter or a digit |
| `accountId` | string (uuid) \| null | no | One of your accounts: the entry then serves only its wallets |
| `family` | string | no | `evm` or `solana`. External: required. Contract: `evm` if sent. Internal: not sent |
| `network` | string | no | `mainnet` or `testnet`. External and contract: required |
| `chain` | string \| null | no | An EVM chain's slug; `null` or `evm`: every EVM chain of the network; Solana: `solana` or `null`. Contract: required, a slug |
| `address` | string | no | External and contract: required. EVM: `0x` + 40 hex (a mixed-case one with its right checksum); Solana: base58 |
| `walletId` | string (uuid) | no | Internal: required — one of your tenant's wallets |

**Responses**

`201` Created

```json
{
  "id": "8f3c2a71-5d4e-4b9a-a6c1-2e7f9d0b3c58",
  "accountId": null,
  "kind": "external",
  "family": "evm",
  "network": "mainnet",
  "chain": "base",
  "chainId": null,
  "address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
  "walletId": null,
  "label": "Supplier payouts",
  "tags": ["suppliers"],
  "customerRefId": "SUP-0042",
  "status": "cooling",
  "version": 1,
  "requestedBy": "0d2f6b8a-4c1e-4a93-b7d5-2e9f1c3a8b60",
  "requestedScope": "tenant",
  "requestedAt": "2026-10-08T08:00:12.000Z",
  "approval": {
    "approvedBy": null,
    "approvedScope": "tenant",
    "approvedAt": "2026-10-08T08:00:12.000Z",
    "requiredApprovals": 0
  },
  "coolingPeriodSeconds": 86400,
  "activeAt": "2026-10-09T08:00:12.000Z",
  "coolingSecondsLeft": 86400,
  "proof": { "proven": false, "method": null, "provenAt": null },
  "rejectedBy": null,
  "rejectedAt": null,
  "removedBy": null,
  "removedAt": null,
  "createdAt": "2026-10-08T08:00:12.000Z",
  "updatedAt": "2026-10-08T08:00:12.000Z"
}
```

`400` Checksum

```json
{
  "statusCode": 400,
  "error": "BadRequestError",
  "message": "The address has a wrong EIP-55 checksum: check it for a typo, or send it in lower case",
  "details": { "code": "ADDRESS_BOOK_ADDRESS_CHECKSUM_INVALID", "field": "address" }
}
```

`409` Exists

```json
{
  "statusCode": 409,
  "error": "ConflictError",
  "message": "The book already holds a live entry for this address, chain and account",
  "details": { "code": "ADDRESS_BOOK_ENTRY_EXISTS" }
}
```

`422` Not a contract

```json
{
  "statusCode": 422,
  "error": "ValidationError",
  "message": "No contract exists at this address on chain 8453",
  "details": { "code": "ADDRESS_BOOK_ADDRESS_NOT_A_CONTRACT", "field": "address", "chainId": 8453 }
}
```

`503` Unverified

```json
{
  "statusCode": 503,
  "error": "ServiceUnavailableError",
  "message": "The contract cannot be checked: the node for chain 8453 did not answer",
  "details": { "code": "ADDRESS_BOOK_CONTRACT_UNVERIFIED", "chainId": 8453, "retryable": true }
}
```

**Example request**

```bash
# Someone else's address, on Base only
curl -X POST https://api.aureahub.com/v1/address-book/entries \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "external", "label": "Supplier payouts", "tags": ["suppliers"], "customerRefId": "SUP-0042",
        "family": "evm", "network": "mainnet", "chain": "base",
        "address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed" }'

# One of your own wallets
curl -X POST https://api.aureahub.com/v1/address-book/entries \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "internal", "label": "Treasury", "walletId": "7c1e9b24-3f5a-4d8e-9b6c-1a2f3e4d5c6b" }'

# A contract your operations call
curl -X POST https://api.aureahub.com/v1/address-book/entries \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "contract", "label": "Swap router", "network": "mainnet", "chain": "base",
        "address": "0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359" }'
```

---

Web version: https://docs.aureahub.com/#address-book-entry-add