# Create external address

Import an externally managed address for tracking.

Endpoint: POST /addresses/external
Version: 1.4.1
Security: Auth

## Security:

  - `Auth` (unknown)
    apiKey in header X-Api-Key scopes: api:address:write

## Request body:

  - `application/json` (unknown)
    External address payload.

## Request fields (application/json):

  - `value` (string, required)
    Blockchain address in its native format.
**Format by network**:
- **EVM**: `0x` + 40 hex chars (normalized to [EIP-55](https://eips.ethereum.org/EIPS/eip-55) checksum on import)
- **Bitcoin**: P2PKH (1...), P2SH (3...), P2WPKH (bc1...)
- **Solana**: Base58, 32-44 chars
- **Tron**: Base58, starts with `T`
    Example: 0x8521E8b15eCEF4D4269Fded3E6694225E096959E

  - `chainFamily` (string, required)
    Chain family that identifies blockchain ecosystems united by common protocol or account model.
    Enum: "evm", "bitcoin", "solana", "tron"

  - `label` (string)
    User-friendly label for the address.
    Example: user_deposit_wallet

  - `meta` (object)
    Optional key-value pairs attached to the address for tracking user associations,
source information, or custom application data.
The combined UTF-8 size of the decoded keys and values must not exceed 4096 bytes.
    Example: {"user_id":"12345","source":"exchange","category":"trading"}

## Response 200:

  - `200` (unknown)
    Created external address.

## Response 200 fields (application/json):

  - `item` (object, required)
    Externally managed address imported for tracking, either directly or from a raw public key.
    Example: {"value":"0xCa79F73628E5D46Cc2c0F6CcD3a3F934d3cE66B7","format":"evm","label":"cold_wallet","kind":"external","tag_ids":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"meta":{"source":"binance","type":"withd…

  - `item.value` (string, required)
    Blockchain address in its native format.
**Format by network**:
- **EVM**: `0x` + 40 hex chars (normalized to [EIP-55](https://eips.ethereum.org/EIPS/eip-55) checksum on import)
- **Bitcoin**: P2PKH (1...), P2SH (3...), P2WPKH (bc1...)
- **Solana**: Base58, 32-44 chars
- **Tron**: Base58, starts with `T`
    Example: 0x8521E8b15eCEF4D4269Fded3E6694225E096959E

  - `item.format` (string, required)
    Blockchain address format that determines how the address should be interpreted and validated.
    Enum: "evm", "solana", "tron", "p2pkh", "p2sh", "p2wpkh", "p2wsh", "p2tr", "p2pkh-testnet", "p2sh-testnet", "p2wpkh-testnet", "p2wsh-testnet", "p2tr-testnet"

  - `item.label` (string)
    User-friendly label for the address.
    Example: user_deposit_wallet

  - `item.kind` (string, required)
    Enum: "external"

  - `item.meta` (object)
    Optional key-value pairs attached to the address for tracking user associations,
source information, or custom application data.
The combined UTF-8 size of the decoded keys and values must not exceed 4096 bytes.
    Example: {"user_id":"12345","source":"exchange","category":"trading"}

  - `item.tag_ids` (array, required)
    IDs of the address tags assigned to this address. The full tag for each ID is included in `references.address_tags`.

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

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

  - `references` (object, required)
    Related objects included in the response, keyed by ID.
    Example: {"public_keys":{},"address_tags":{}}

  - `references.public_keys` (object, required)
    Map of public keys indexed by their UUID ID.

  - `references.address_tags` (object, required)
    Map of address tags indexed by their UUID ID.

## Response 201:

  - `201` (unknown)
    Created external address.

## Response 201 fields (application/json):

  - `item` (object, required)
    Externally managed address imported for tracking, either directly or from a raw public key.
    Example: {"value":"0xCa79F73628E5D46Cc2c0F6CcD3a3F934d3cE66B7","format":"evm","label":"cold_wallet","kind":"external","tag_ids":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"meta":{"source":"binance","type":"withd…

  - `item.value` (string, required)
    Blockchain address in its native format.
**Format by network**:
- **EVM**: `0x` + 40 hex chars (normalized to [EIP-55](https://eips.ethereum.org/EIPS/eip-55) checksum on import)
- **Bitcoin**: P2PKH (1...), P2SH (3...), P2WPKH (bc1...)
- **Solana**: Base58, 32-44 chars
- **Tron**: Base58, starts with `T`
    Example: 0x8521E8b15eCEF4D4269Fded3E6694225E096959E

  - `item.format` (string, required)
    Blockchain address format that determines how the address should be interpreted and validated.
    Enum: "evm", "solana", "tron", "p2pkh", "p2sh", "p2wpkh", "p2wsh", "p2tr", "p2pkh-testnet", "p2sh-testnet", "p2wpkh-testnet", "p2wsh-testnet", "p2tr-testnet"

  - `item.label` (string)
    User-friendly label for the address.
    Example: user_deposit_wallet

  - `item.kind` (string, required)
    Enum: "external"

  - `item.meta` (object)
    Optional key-value pairs attached to the address for tracking user associations,
source information, or custom application data.
The combined UTF-8 size of the decoded keys and values must not exceed 4096 bytes.
    Example: {"user_id":"12345","source":"exchange","category":"trading"}

  - `item.tag_ids` (array, required)
    IDs of the address tags assigned to this address. The full tag for each ID is included in `references.address_tags`.

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

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

  - `references` (object, required)
    Related objects included in the response, keyed by ID.
    Example: {"public_keys":{},"address_tags":{}}

  - `references.public_keys` (object, required)
    Map of public keys indexed by their UUID ID.

  - `references.address_tags` (object, required)
    Map of address tags indexed by their UUID ID.

## Response 400:

  - `400` (unknown)
    Bad request (e.g., missing or invalid fields). Invalid text may be reported as address.label_invalid, address.meta_invalid, public_key.label_invalid, invoice.comment_invalid, invoice.metadata_invalid.

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

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

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

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

  - `fields.reason` (string, required)
    Why this field is invalid.
    Example: 32

## Response 401:

  - `401` (unknown)
    Missing or invalid authentication credentials.

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

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response 403:

  - `403` (unknown)
    Insufficient permissions.

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

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response 409:

  - `409` (unknown)
    Request conflicts with the current resource state.

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

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response default:

  - `default` (unknown)
    Unexpected error.

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

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response 400 examples:

  - `The create-invoice request body contains malformed JSON` (unknown)

## Response 401 examples:

  - `The API service refused authentication` (unknown)

## Response 403 examples:

  - `The API key lacks the required permission` (unknown)

## Response 409 examples:

  - `The address already has an active invoice` (unknown)

  - `The address cannot be deleted while in use` (unknown)