# Create account

Create an account and start its setup automatically. The vault must be active, support the selected address format and have no other account being created. No further approval is needed; check the account status until it becomes active.
Reuse the same Idempotency-Key with the same parameters when retrying this request. Current access is checked on every retry. The original successful response is available for 24 hours from successful completion; replay does not repeat the action. Concurrent requests with the same key return 409 idempotency_in_progress, changed parameters return idempotency_request_mismatch, and expired replay returns idempotency_result_expired. Missing, invalid or repeated headers return 400.

Endpoint: POST /accounts
Version: 1.0.0
Security: Auth

## Security:

  - `Auth` (unknown)
    apiKey in header X-Api-Key scopes: vks:access

## 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):

  - `address_format` (string, required)
    Address format used by the account.
    Enum: "evm", "solana", "tron", "p2pkh", "p2sh", "p2wpkh", "p2wsh", "p2tr", "p2pkh-testnet", "p2sh-testnet", "p2wpkh-testnet", "p2wsh-testnet", "p2tr-testnet"

  - `label` (string)
    Optional display name for the account.

  - `vault_id` (string, required)

## Request examples:

  - `Create an EVM account` (unknown)
    Use an active vault whose signers support EVM accounts.

  - `Create a Tron account` (unknown)
    Use an active vault whose signers support Tron accounts.

  - `Create a native SegWit Bitcoin account` (unknown)
    Use an active vault whose signers support this Bitcoin address format.

## Response 201:

  - `201` (unknown)
    The new account, in `pending`.

## Response 201 fields (application/json):

  - `item` (object, required)
    An account with its blockchain address and current setup status.

  - `item.account_id` (string, required)
    Unique identifier of the account.

  - `item.vault_id` (string, required)
    Vault that controls this account.

  - `item.address_format` (string, required)
    Address format used by the account.
    Enum: "evm", "solana", "tron", "p2pkh", "p2sh", "p2wpkh", "p2wsh", "p2tr", "p2pkh-testnet", "p2sh-testnet", "p2wpkh-testnet", "p2wsh-testnet", "p2tr-testnet"

  - `item.chain_family` (string, required)
    Blockchain family supported by the account.
    Enum: "evm", "bitcoin", "tron", "solana"

  - `item.suite` (string, required)
    Signing protocol used by this account.

  - `item.key_epoch` (integer, required)
    Version of the account signing key. Zero identifies the initial version, including after activation.

  - `item.state` (string, required)
    Account setup status. Only active accounts can sign transactions.
    Enum: "pending", "dkg_running", "attesting", "self_testing", "certifying", "active", "failed", "expired", "aborted"

  - `item.public_key` (any, required)
    Public key of the account. Null until key generation is complete.

  - `item.address` (any, required)
    Blockchain address of the account. Null until the address is available.

  - `item.certificate_hash` (string)
    Hash used to verify the account certificate. Available when the account becomes active.

  - `item.label` (string)
    Display name chosen for the account. Absent when no name was set.

  - `item.failure_code` (string)
    Code indicating why the account could not be created. Present only after a failure.

  - `item.caip10` (string)
    Account address qualified by its blockchain identifier (CAIP-10). Included when a supported chain_gid is provided and the account address is available.

  - `item.attempts` (array, required)
    Account setup attempts, oldest first. Use an attempt identifier to view its state and result.

  - `item.attempts.attempt_id` (string, required)
    Unique identifier of this setup attempt.

  - `item.attempts.account_id` (string, required)
    Account being set up.

  - `item.attempts.kind` (string, required)
    Setup step: generating the account key or checking that the selected signers can use it.
    Enum: "dkg", "activation"

  - `item.attempts.state` (string, required)
    Progress of this account setup attempt.
    Enum: "created", "starting", "running", "succeeded", "failed", "aborted", "expired"

  - `item.attempts.quorum_signer_ids` (array)
    Signers taking part in this activation check. Absent for key-generation attempts.

  - `item.attempts.failure_code` (string)
    Code indicating why the setup attempt failed. Absent if no failure occurred.

  - `item.attempts.failure_message` (string)
    Explanation of why the setup attempt failed. Absent if no failure occurred.

  - `item.attempts.created_at` (string, required)
    Time the setup attempt started.

  - `item.attempts.expires_at` (string, required)
    Deadline for completing the setup attempt.

  - `item.created_at` (string, required)
    Time the account was created.

  - `item.expires_at` (string, required)
    Deadline for completing account setup, including key generation, verification and certificate issuance.

## Response 400:

  - `400` (unknown)
    Some request values are missing or invalid. Check fields for details.

## 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)
    Authentication is required to make this request.

## 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)
    You do not have permission to access VKS in this workspace.

## 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 404:

  - `404` (unknown)
    The requested resource could not be found.

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

  - `503` (unknown)
    The service is temporarily unavailable. 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)
    Details of an error that prevented the request from completing.

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

  - `Invalid request` (unknown)

## Response 404 examples:

  - `Transaction not found` (unknown)

## Response 409 examples:

  - `Account is not ready to sign transactions` (unknown)

  - `Transaction state does not allow this operation` (unknown)

  - `Another send is in progress` (unknown)

  - `Transaction already accepted` (unknown)

## Response default examples:

  - `Unexpected failure` (unknown)