> ## Documentation Index > Fetch the complete documentation index at: https://docs.octav.fi/llms.txt > Use this file to discover all available pages before exploring further. # Add Address Book Entries > Add one or more addresses to the address book. An address already in the book keeps its existing label — this endpoint never overwrites one. Only addresses not already in the book count against the account's non-paid address quota. Returns the entire address book after the add, not just the entries sent. **Cost:** 1 credit per call. Automatically refunded on 4xx/5xx responses. **Access:** Requires portfolio entitlement — the same flag that unlocks `/v1/portfolio`. **Rate limit:** 360 req/min (shared with portfolio bucket) **Get your API key:** [Dev Portal](https://data.octav.fi) ## OpenAPI ````yaml /openapi.json post /addressbook openapi: 3.0.0 info: title: Octav API description: >- Comprehensive blockchain data API for portfolio management, transactions, and DeFi analytics version: 1.0.0 contact: name: Octav Support url: https://octav.fi email: info@octav.fi servers: - url: https://api.octav.fi/v1 description: Production API security: - bearerAuth: [] tags: - name: Portfolio description: Portfolio and holdings endpoints - name: Virtual Users description: Virtual user management and portfolio endpoints (Pro only) - name: Nav description: Net Asset Value endpoints - name: Wallet description: Wallet information endpoints - name: Transactions description: Transaction history endpoints - name: Approvals description: Token approval endpoints - name: Tokens description: Token data endpoints - name: Airdrops description: Airdrop eligibility endpoints - name: Sync description: Data synchronization endpoints - name: Status description: Status check endpoints - name: Credits description: Credit balance endpoints - name: Chains description: Blockchain network and protocol endpoints - name: Contract Protocol description: Resolve a contract address to its DeFi protocol - name: Agent (x402) description: >- Pay-per-call endpoints for autonomous agents via the x402 protocol — no API key. A five-endpoint subset; the API-key REST endpoints above are the default. - name: Beacon Validators description: >- Ethereum beacon chain validator endpoints — details, rewards, withdrawals, and deposits (mainnet only) - name: Address Book description: >- Manage the wallet addresses saved to your account — the list a bundle draws from - name: Bundles description: Group saved address book addresses into named bundles paths: /addressbook: post: tags: - Address Book summary: Add Address Book Entries description: >- Add one or more addresses to the address book. An address already in the book keeps its existing label — this endpoint never overwrites one. Only addresses not already in the book count against the account's non-paid address quota. Returns the entire address book after the add, not just the entries sent. **Cost:** 1 credit per call. Automatically refunded on 4xx/5xx responses. **Access:** Requires portfolio entitlement — the same flag that unlocks `/v1/portfolio`. **Rate limit:** 360 req/min (shared with portfolio bucket) **Get your API key:** [Dev Portal](https://data.octav.fi) operationId: addAddressbookEntries requestBody: required: true content: application/json: schema: type: object properties: entries: type: array minItems: 1 maxItems: 100 description: >- Addresses to add. At least 1, at most 100 per request. Addresses must be unique within the request. items: type: object properties: address: type: string description: >- EVM, Solana, Starknet, or Tron address. Normalized server-side. label: type: string maxLength: 255 description: >- Optional name, up to 255 characters. May be an empty string. Defaults to "" when omitted, and is ignored for an address already in the book. required: - address required: - entries example: entries: - address: '0x6426af179aabebe47666f345d69fd9079673f6cd' label: Treasury - address: 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM responses: '200': description: The full address book after the add content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/AddressBookEntry' example: data: - address: '0x6426af179aabebe47666f345d69fd9079673f6cd' label: Treasury plan: PRO expiresAt: '2026-11-01T00:00:00.000Z' isPaid: true - address: 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM label: '' plan: FREE expiresAt: null isPaid: false '400': $ref: '#/components/responses/ApiErrorBadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '404': $ref: '#/components/responses/ApiErrorNotFound' '422': $ref: '#/components/responses/ApiErrorUnprocessable' '500': $ref: '#/components/responses/ApiErrorInternal' security: - bearerAuth: [] components: schemas: AddressBookEntry: type: object description: An address book entry. Keyed by address — there is no id field. properties: address: type: string description: >- The normalized wallet address. This is the entry's identifier; use it in the path of the rename and remove endpoints. label: type: string description: User-defined name. Empty string when no label was given. plan: type: string enum: - FREE - LITE - PRO description: Plan covering this address. expiresAt: type: string format: date-time nullable: true description: >- When the plan on this address lapses. null on FREE addresses, which never had a paid period. isPaid: type: boolean description: >- Derived from expiresAt: true only when expiresAt is set and still in the future. A lapsed paid address reports false while keeping its expiresAt. example: address: '0x6426af179aabebe47666f345d69fd9079673f6cd' label: Treasury plan: PRO expiresAt: '2026-11-01T00:00:00.000Z' isPaid: true ApiErrorEnvelope: type: object description: >- Domain failures on the address book and bundle routes answer with this envelope. Some codes add extra fields alongside code and message. properties: error: type: object properties: code: type: string enum: - VALIDATION_ERROR - UNAUTHORIZED - ADDRESSBOOK_ENTRY_NOT_FOUND - ADDRESSBOOK_QUOTA_REACHED - ADDRESSBOOK_ENTRY_NOT_DELETABLE - BUNDLE_NOT_FOUND - BUNDLE_QUOTA_REACHED - BUNDLE_SIZE_LIMIT_EXCEEDED - BUNDLE_NAME_TAKEN - BUNDLE_MEMBERS_ALREADY_BUNDLED - BUNDLE_EMPTY - BUNDLE_ADDRESS_NOT_IN_ADDRESS_BOOK - DELEGATE_NOT_FOUND - INTERNAL_ERROR message: type: string quota: type: integer description: The limit that was reached. current: type: integer description: Current count against that limit. limit: type: integer description: Maximum addresses a bundle may hold. name: type: string description: Bundle name that is already taken. bundleId: type: string description: Bundle that already holds these addresses. addresses: type: array items: type: string description: Addresses that are not in the address book. required: - code - message responses: ApiErrorBadRequest: description: >- VALIDATION_ERROR — an address is malformed or unsupported, or the request repeats an address. Request-schema failures instead return the API-wide { "error": "Validation Failed", "details": [...] } shape, and are rejected before any credit is reserved. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: VALIDATION_ERROR message: One or more addresses are invalid Unauthorized: description: Missing or invalid Bearer token content: application/json: schema: type: object properties: message: type: string example: Unauthorized PaymentRequired: description: Insufficient credit balance. Credit is refunded automatically. content: application/json: schema: type: object properties: message: type: string example: Not enough credits creditsRequired: type: number example: 1 creditsAvailable: type: number example: 0 ApiErrorNotFound: description: ADDRESSBOOK_ENTRY_NOT_FOUND, BUNDLE_NOT_FOUND, or DELEGATE_NOT_FOUND. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: BUNDLE_NOT_FOUND message: Bundle not found ApiErrorUnprocessable: description: >- A business rule rejected the request: ADDRESSBOOK_QUOTA_REACHED (adds quota, current), BUNDLE_QUOTA_REACHED (adds quota), BUNDLE_SIZE_LIMIT_EXCEEDED (adds limit), BUNDLE_EMPTY, or BUNDLE_ADDRESS_NOT_IN_ADDRESS_BOOK (adds addresses). content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: BUNDLE_ADDRESS_NOT_IN_ADDRESS_BOOK message: >- Not in the address book: 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984. Add them before bundling them. addresses: - '0x1f9840a85d5af5bf1d1762f925bdaddc4201f984' ApiErrorInternal: description: >- INTERNAL_ERROR — unexpected server-side failure. The reserved credit is refunded. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: INTERNAL_ERROR message: Error while fetching the address book securitySchemes: bearerAuth: type: http scheme: bearer ````