> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primevault.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Vault

> Create a new vault in your organization. The vault needs your API user's approval before it takes effect.

**POST** `/api/external/vaults/`

## Request body

<ParamField body="vaultName" type="string" required>
  Vault name. Cannot be blank. Naming it "NGN" does not set its asset; asset is not a create input.
</ParamField>

<ParamField body="subOrgId" type="string">
  Sub-org that owns the vault.
</ParamField>

<ParamField body="chains" type="string[]">
  Requested wallet chains. Use identifiers from [Assets and Chains](/assets-and-chains/overview).
</ParamField>

<ParamField body="testNetVault" type="boolean">
  Creates a testnet vault when supported. Default: false.
</ParamField>

<ParamField body="vaultGroupIds" type="string[]">
  Organization-scoped vault groups to attach.
</ParamField>

## Response

Returns the new [Vault](/api-basics/data-models#vault). Wallet addresses can be generated after the response, so retrieve the vault until `walletsGenerated` is `true` before using them.

<ResponseField name="id" type="string">
  Vault ID.
</ResponseField>

<ResponseField name="orgId" type="string">
  Organization that owns the vault.
</ResponseField>

<ResponseField name="subOrgId" type="string">
  [Sub-org](/sub-orgs/overview) that owns the vault, if any.
</ResponseField>

<ResponseField name="vaultName" type="string">
  Vault name.
</ResponseField>

<ResponseField name="vaultType" type="VaultType">
  `DEFAULT`, `EXCHANGE`, or `GAS`. See [VaultType](/api-basics/data-models#vaulttype).
</ResponseField>

<ResponseField name="asset" type="string | null">
  Currency of a multi-currency account vault, for example `NGN`. `null` for self-custody vaults.
</ResponseField>

<ResponseField name="wallets" type="object[]">
  Blockchain wallets in the vault.

  <Expandable title="Properties">
    <ResponseField name="id" type="string">
      Wallet ID.
    </ResponseField>

    <ResponseField name="blockchain" type="string">
      Chain the wallet is on.
    </ResponseField>

    <ResponseField name="address" type="string">
      Wallet address. Missing until the wallet is generated.
    </ResponseField>

    <ResponseField name="publicKey" type="string">
      Wallet public key.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="walletsGenerated" type="boolean">
  Whether wallet addresses are ready. Wait for `true` before using `wallets`.
</ResponseField>

<ResponseField name="createdAt" type="string">
  Creation timestamp (ISO 8601).
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Last update timestamp (ISO 8601).
</ResponseField>

<ResponseField name="isDeleted" type="boolean">
  Whether the vault is deleted.
</ResponseField>

## Approve the vault

Creating a vault opens a change request that your API user must approve. Call [Get Approval Message](/approvals/get-approval-message) with `entityId` set to the vault `id`, sign the `message`, and send the signature to [Submit Approval Action](/approvals/submit-approval-action). See [Approvals](/approvals/overview) for the full flow.

With the SDK, approve separately or in one call:

```typescript theme={null}
const vault = await apiClient.createVault(request);
const approvedVault = await apiClient.createVaultApproval(vault);

// Convenience helper: create, then approve.
const approved = await apiClient.createVaultWithApproval(request);
```

After approval, retrieve the vault until `walletsGenerated === true` before using its wallet addresses. Approval does not make wallet generation synchronous.

<RequestExample dropdown>
  ```json Request example theme={null}
  {
    "vaultName": "Treasury Vault",
    "subOrgId": "sub_org_123",
    "chains": ["ETHEREUM", "POLYGON"],
    "testNetVault": false,
    "vaultGroupIds": ["vault_group_123"]
  }
  ```

  ```bash cURL theme={null}
  # Sample only. Generate a new signed token for each request
  # (see Authentication). Tokens expire after 120 seconds.
  curl --request POST \
    --url "https://api.primevault.com/api/external/vaults/" \
    --header "Authorization: Bearer <signed JWT>" \
    --header "Api-Key: <API key>" \
    --header "Content-Type: application/json" \
    --data '{
      "vaultName": "Treasury Vault",
      "subOrgId": "sub_org_123",
      "chains": [
        "ETHEREUM",
        "POLYGON"
      ],
      "testNetVault": false,
      "vaultGroupIds": [
        "vault_group_123"
      ]
    }'
  ```

  ```typescript JavaScript SDK theme={null}
  interface CreateVaultRequest {
    vaultName: string;
    subOrgId?: string;
    chains?: string[];
    testNetVault?: boolean;
    vaultGroupIds?: string[];
  }

  createVault(request: CreateVaultRequest): Promise<Vault>
  ```
</RequestExample>

<ResponseExample dropdown>
  ```json Response example theme={null}
  {
    "id": "vault_123",
    "orgId": "org_456",
    "subOrgId": "sub_org_123",
    "vaultName": "Treasury Vault",
    "vaultType": "DEFAULT",
    "wallets": [],
    "walletsGenerated": false,
    "createdAt": "2026-08-04T10:30:00Z",
    "updatedAt": "2026-08-04T10:30:00Z",
    "isDeleted": false,
    "asset": null
  }
  ```

  ```typescript JavaScript SDK theme={null}
  interface Vault {
    id: string;
    orgId: string;
    subOrgId?: string;
    vaultName: string;
    vaultType: VaultType;
    asset?: string | null;
    wallets: Array<{
      id: string;
      blockchain: string;
      address?: string;
      publicKey?: string;
    }>;
    walletsGenerated: boolean;
    createdAt: string;
    updatedAt: string;
    isDeleted: boolean;
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.