# List accounts

List accounts with filtering, sorting and pagination. Values within one filter match any value; different filters apply together. Only active accounts can sign transactions.

Endpoint: GET /accounts
Version: 1.0.0
Security: Auth

## Security:

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

## Query parameters:

  - `vault_id` (array)
    Filter accounts by vault.

  - `address` (array)
    Filter accounts by complete blockchain address.

  - `address_format` (array)
    Filter accounts by address format.

  - `state` (array)
    Filter accounts by setup status.

  - `page` (integer)
    Page number, starting at 1.

  - `limit` (integer)
    Maximum number of items per page. Defaults to 30; values above 100 return at most 100 items.

  - `sort` (string)
    Sort field and direction for accounts. Prefix with `-` for descending.

## Response 200:

  - `200` (unknown)
    One page of matching accounts.

## Response 200 fields (application/json):

  - `items` (array, required)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  - `meta` (object, required)
    Pagination metadata returned on every list response. `page` and `limit` echo the values used to build this page (defaults are applied when the request omits them). `total` and `total_pages` reflect the full result set after any filters are applied.
    Example: {"limit":20,"page":1,"total":42,"total_pages":3}

  - `meta.limit` (integer, required)
    Page size used to build this response.

  - `meta.page` (integer, required)
    Index of the page returned, starting at 1.

  - `meta.total` (integer, required)
    Total number of items matching the request across all pages.

  - `meta.total_pages` (integer, required)
    Total number of pages available at the current `limit`.

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

  - `Unexpected failure` (unknown)