# Create external address

Import an externally managed address for tracking, given the address itself or the raw public key it derives from. Answers 200 with the existing address when the value is already tracked, 201 when it was created.

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

## Security:

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

## Header parameters:

  - `Idempotency-Key` (string, required)
    Case-sensitive opaque key for one mutation intent. Send exactly one header occurrence containing 1 to 128 visible ASCII bytes (0x21..0x7e). Commas are literal data; do not trim, lowercase or require UUID syntax. Reuse the same key for retries, with current authorization checked on every attempt. Repeated header occurrences are rejected.

## Request fields (application/json):

  - `input` (any, required)
    What identifies the address to import: the address itself, or the raw public key it
derives from.

  - `input.source` (string, required)
    Input kind, the discriminator of `ExternalAddressInput`.
    Enum: "address", "public_key"

  - `input.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

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

  - `input.public_key` (string, required)
    Raw public key. Hex-encoded for secp256k1 chains (EVM, Tron, Bitcoin), base58-encoded
for ed25519 chains (Solana). Compressed (33 bytes) and uncompressed (65 bytes) secp256k1
keys are both accepted; the 0x prefix is optional for hex keys.
    Example: 02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5

  - `input.address_format` (string, required)
    Address format to derive from a public key. A subset of `AddressFormat`: script formats
such as p2wsh cannot be derived from a single key.
    Enum: "evm", "tron", "solana", "p2pkh", "p2sh", "p2wpkh", "p2pkh-testnet", "p2sh-testnet", "p2wpkh-testnet"

  - `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"}

## Request examples:

  - `Import an address` (unknown)

  - `Import the address a public key derives to` (unknown)

## 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":{"exchange":"binance","type":"wit…

  - `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":{"exchange":"binance","type":"wit…

  - `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 429:

  - `429` (unknown)
    Resource quota exceeded. The response includes the effective limit for this scope. The applicable code and limit depend on the operation; examples illustrate different limits.

## Response 429 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 code identifying the exhausted resource quota. The code is always
supplied by the service; clients branch on it instead of the human-readable detail.
    Example: address.quota_exceeded

  - `max` (integer, required)
    Effective maximum for this resource in the caller's scope. Zero prohibits new admissions;
it does not disable resources already held. This is the configured limit, not current usage.
    Example: 100

## Response 503:

  - `503` (unknown)
    The operation is temporarily unavailable. Please try again later.

## Response 503 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 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)

  - `A v1-created subscription rejects trigger, filter or noise changes` (unknown)

  - `The notification already has a manual attempt queued or in flight` (unknown)

  - `Retention has cleared the content, so there is nothing to resend` (unknown)

  - `The notification is a channel test` (unknown)

## Response 429 examples:

  - `The project has reached its address quota` (unknown)

  - `A zero effective limit prohibits new resources` (unknown)

## Response 503 examples:

  - `The operation cannot be completed at present` (unknown)