# Import external address

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.

Endpoint: POST /addresses/external
Version: 1.0.0
Security: ApiKeyAuth

## Request fields (application/json):

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

  - `chainFamily` (string, required)
    Chain family that identifies blockchain ecosystems united by common protocol or account model.

Available families:
- evm: Ethereum Virtual Machine-based blockchains
- bitcoin: Bitcoin and Bitcoin-compatible networks
- solana: Solana blockchain ecosystem
- tron: Tron blockchain ecosystem

The chain family is used to determine which blockchain ecosystem
the address belongs to and how it should be generated or validated.
    Enum: "evm", "bitcoin", "solana", "tron"

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

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

## Response 200 fields (application/json):

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

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

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

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

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

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

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

## Response 201 fields (application/json):

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

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

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

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

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

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

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

## 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"