# Get all HD addresses

Returns a list of all HD addresses derived from all public keys in the system.
This endpoint provides a consolidated view of all HD addresses across all public keys,
with support for filtering, sorting and pagination.

Endpoint: GET /addresses/hd
Version: 1.0.0
Security: ApiKeyAuth

## Query parameters:

  - `limit` (integer)
    Maximum number of items to return
    Example: 20

  - `page` (integer)
    Page number for pagination
    Example: 1

  - `sort_by` (string)
    Field to sort results by. Use "-" prefix for descending order
    Enum: "label", "-label", "address", "-address", "created_at", "-created_at", "updated_at", "-updated_at"

  - `formats` (array)
    Comma-separated list of address formats to include.
    Enum: "evm", "solana", "tron", "p2pkh", "p2sh", "p2wpkh", "p2wsh", "p2pkh-testnet", "p2sh-testnet", "p2wpkh-testnet", "p2wsh-testnet"

  - `search` (string)
    Performs a partial, case-insensitive match on address or label fields.
    Example: "bc1q"

  - `is_archived` (boolean)
    When true, returns only archived addresses. When false, returns only active ones.

## Response 200 fields (application/json):

  - `items` (array, required)
    List of HD addresses derived from the public key

  - `items.value` (string, required)
    A blockchain address in its native format. This is a generic schema for any blockchain address,
including addresses, smart contract addresses, and token contract addresses.

The actual format depends on the blockchain network:

- EVM chains (Ethereum, BSC, Polygon, etc.): 0x followed by 40 hexadecimal characters
  - Example: 0x8521E8b15eCEF4D4269Fded3E6694225E096959E

- Bitcoin: Various formats depending on address type
  - P2PKH (Legacy): Starts with 1, Example: 1GxHzNEymq1MLhxpdWAMJLN1UusYJ2Sy45
  - P2SH (Wrapped SegWit): Starts with 3, Example: 3Do92Dmff87UuY9Yiu2iFG2Kj9bpRaeJSF
  - P2WPKH (Native SegWit): Starts with bc1, Example: bc1q8faxe8g4u2v67qfwf9d8xhyl5tkkkphvet6r08

- Solana: Base58 encoded, 32-44 characters
  - Example: 5EYCAe5ijiHbZBU14TyKHADUrkaAfc4ZyTXKRVKp49F8

- Tron: Base58 encoded addresses starting with T
  - Example: TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t

- Cosmos ecosystem: Bech32 format with chain-specific prefix
  - Example: cosmos1vx8knpllrj7n963p9ttd80w47kpacrhuts497x

This schema is intentionally generic to support addresses from any blockchain.
The specific validation rules depend on the blockchain network and address type.
    Example: "0x8521E8b15eCEF4D4269Fded3E6694225E096959E"

  - `items.format` (string, required)
    Blockchain address format that determines how the address should be interpreted and validated:

EVM-compatible blockchains:
- evm: Ethereum Virtual Machine compatible address (Ethereum, BSC, Polygon, Arbitrum, etc.)
  - Format: 0x followed by 40 hexadecimal characters
  - Example: 0x742d35Cc6634C0532925a3b844Bc454e4438f44e

Solana:
- solana: Solana address
  - Format: Base58 encoded, 32-44 characters
  - Example: 5EYCAe5ijiHbZBU14TyKHADUrkaAfc4ZyTXKRVKp49F8

Tron:
- tron: Tron address
  - Format: Base58 encoded, starts with T
  - Example: TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH

Bitcoin mainnet formats:
- p2pkh: Pay-to-Public-Key-Hash (Legacy)
  - Format: Starts with 1
  - Example: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa

- p2sh: Pay-to-Script-Hash
  - Format: Starts with 3
  - Example: 3Do92Dmff87UuY9Yiu2iFG2Kj9bpRaeJSF

- p2wpkh: Pay-to-Witness-Public-Key-Hash (Native SegWit)
  - Format: Starts with bc1q
  - Example: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh

- p2wsh: Pay-to-Witness-Script-Hash (Native SegWit)
  - Format: Starts with bc1q
  - Example: bc1qrp33g0q4c70atj6hy6wuahcwxryadxw3kvjahxxxgf7rflwdlcjqqtf3a0

Bitcoin testnet formats:
- p2pkh-testnet: Pay-to-Public-Key-Hash (Legacy testnet)
  - Format: Starts with m or n
  - Example: mipcBbFg9gMiCh81Kj8tqqdgoZub1ZJRfn

- p2sh-testnet: Pay-to-Script-Hash (testnet)
  - Format: Starts with 2
  - Example: 2MzQwSSnBHWHqSAqtTVQ6v47XtaisrJa1Vc

- p2wpkh-testnet: Pay-to-Witness-Public-Key-Hash (Native SegWit testnet)
  - Format: Starts with tb1q
  - Example: tb1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh

- p2wsh-testnet: Pay-to-Witness-Script-Hash (Native SegWit testnet)
  - Format: Starts with tb1q
  - Example: tb1qrp33g0q4c70atj6hy6wuahcwxryadxw3kvjahxxxgf7rflwdlcjqqtf3a0
    Enum: "evm", "solana", "tron", "p2pkh", "p2sh", "p2wpkh", "p2wsh", "p2pkh-testnet", "p2sh-testnet", "p2wpkh-testnet", "p2wsh-testnet"

  - `items.label` (string,null)
    User-friendly label for the address
    Example: "user_45_deposit"

  - `items.kind` (string, required)
    Kind of address in the system:
- hd: HD (Hierarchical Deterministic) address derived from an extended public key
- external: External address imported directly without derivation
    Enum: "hd", "external"

  - `items.meta` (object)
    Optional metadata as key-value pairs for storing additional information about the address.
Total size of all keys and values combined must not exceed 1000 characters.

Common use cases:
- Tracking user associations (user_id, account_id)
- Recording source information (exchange, wallet, service)
- Business logic flags (archived, locked, category)
- Custom application data
    Example: {"user_id":"12345","source":"exchange","category":"trading"}

  - `items.created_at` (string, required)
    Timestamp when the resource was created
    Example: "2024-01-15T10:30:00Z"

  - `items.updated_at` (string, required)
    Timestamp when the resource was last updated
    Example: "2024-01-15T10:30:00Z"

  - `items.public_key_id` (string, required)
    Unique identifier in UUID format
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `items.derivation_index` (integer, required)
    Address index in the HD wallet derivation sequence
    Example: 45

  - `meta` (object, required)

  - `meta.limit` (integer, required)
    Number of items per page
    Example: 20

  - `meta.page` (integer, required)
    Current page number
    Example: 1

  - `meta.total` (integer, required)
    Total number of items available
    Example: 42

  - `meta.total_pages` (integer, required)
    Total number of pages available
    Example: 3

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    A URI reference that identifies the problem type
    Example: "https://docs.vilna.io/apis/problems/invalid-request"

  - `title` (string, required)
    A short, human-readable summary of the problem type
    Example: "Invalid Request"

  - `status` (integer, required)
    The HTTP status code
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem
    Example: "Validation error"

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem
    Example: "/errors?id=XXXXXX-xxxxx"

  - `fields` (array)
    List of invalid fields in the request

  - `fields.name` (string, required)
    The name of the invalid field
    Example: "meta"

  - `fields.reason` (string, required)
    Why this field is invalid
    Example: "Exceeded maximum data size — must not exceed 1000 characters"

## Response default fields (application/problem+json):

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem
    Example: "An unexpected error occurred while processing your request"

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem
    Example: "/errors/1234567890"

  - `status` (integer, required)
    The HTTP status code
    Example: 500

  - `title` (string, required)
    A short, human-readable summary of the problem type
    Example: "Internal Server Error"

  - `type` (string, required)
    A URI reference that identifies the problem type
    Example: "https://api.vilna.io/problems/internal-error"