# address

Address management operations for tracking blockchain addresses

## Get addresses derived from public key

 - [GET /public_keys/{public_key_id}/addresses](https://docs.vilna.io/apis/spec/public_key/listpublickeyaddresses.md): Returns a list of all addresses derived from this public key.
These are HD addresses generated using the public key's derivation path
and various indexes. The addresses are sorted by index by default.

## Generate addresses from public key

 - [POST /public_keys/{public_key_id}/addresses](https://docs.vilna.io/apis/spec/public_key/generatepublickeyaddresses.md): Generates multiple HD addresses from the public key using either specific indexes or a range.
The address format is automatically determined based on the public key's derivation path.

You can specify either:
- A list of specific indexes to generate addresses for
- A range (from/to) to generate consecutive addresses

If neither is specified, generates a single address at the next available index.

## Generate next address from public key

 - [POST /public_keys/{public_key_id}/addresses/next](https://docs.vilna.io/apis/spec/public_key/generatenextpublickeyaddress.md): Generates the next HD address from the public key by automatically determining the next available index.

The system finds the highest existing index and generates the next sequential address. This is ideal for
payment processing systems that need unique addresses for each transaction without manual index tracking.

## Get addresses derived from public key

 - [GET /public_keys/{public_key_id}/addresses](https://docs.vilna.io/apis/spec/address/listpublickeyaddresses.md): Returns a list of all addresses derived from this public key.
These are HD addresses generated using the public key's derivation path
and various indexes. The addresses are sorted by index by default.

## Generate addresses from public key

 - [POST /public_keys/{public_key_id}/addresses](https://docs.vilna.io/apis/spec/address/generatepublickeyaddresses.md): Generates multiple HD addresses from the public key using either specific indexes or a range.
The address format is automatically determined based on the public key's derivation path.

You can specify either:
- A list of specific indexes to generate addresses for
- A range (from/to) to generate consecutive addresses

If neither is specified, generates a single address at the next available index.

## Generate next address from public key

 - [POST /public_keys/{public_key_id}/addresses/next](https://docs.vilna.io/apis/spec/address/generatenextpublickeyaddress.md): Generates the next HD address from the public key by automatically determining the next available index.

The system finds the highest existing index and generates the next sequential address. This is ideal for
payment processing systems that need unique addresses for each transaction without manual index tracking.

## Get list of all addresses

 - [GET /addresses](https://docs.vilna.io/apis/spec/address/listaddresses.md): Returns a list of all addresses (both HD and external).
This endpoint provides a unified view of all addresses in the system.

## Import external address

 - [POST /addresses/external](https://docs.vilna.io/apis/spec/address/createexternaladdress.md): Imports an external address that is not derived from a public key.
This is useful for tracking addresses from hardware wallets, exchanges, or other external sources.

The address format must be specified to ensure proper validation across different blockchain ecosystems.

## Get all HD addresses

 - [GET /addresses/hd](https://docs.vilna.io/apis/spec/address/listhdaddresses.md): 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.

## Delete an address

 - [DELETE /addresses/{address}](https://docs.vilna.io/apis/spec/address/deleteaddress.md): Permanently deletes an address by its blockchain address. This action cannot be undone.

## Get a single address

 - [GET /addresses/{address}](https://docs.vilna.io/apis/spec/address/getaddress.md): Returns details of a specific address by its blockchain address

## Update address metadata

 - [PATCH /addresses/{address}](https://docs.vilna.io/apis/spec/address/patchaddress.md): Updates address

## Get HD address representation

 - [GET /addresses/{address}/hd](https://docs.vilna.io/apis/spec/address/gethdaddress.md): Returns details of an address as HD address type. This endpoint will return
the HD-specific information for an address including derivation details,
public key reference, and HD metadata.

If the address exists but is not an HD address, returns 404.
If the address doesn't exist at all, also returns 404.

## Get external address representation

 - [GET /addresses/{address}/external](https://docs.vilna.io/apis/spec/address/getexternaladdress.md): Returns details of an address as external address type. This endpoint will return
the external-specific information for an address including any imported metadata
and external address properties.

If the address exists but is not an external address, returns 404.
If the address doesn't exist at all, also returns 404.

## Get all active asset balances for an address

 - [GET /addresses/{address}/balances](https://docs.vilna.io/apis/spec/address/getaddressbalances.md): Retrieve current balances for all active assets that have been discovered on the given address.

The response is a simple key-value map where:
- Key: Asset identifier (CAIP-19 format)
- Value: Balance as a decimal string