> ## 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](/accounts-and-wallets/assets-and-chains).
</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.

## 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>
  ```json Response 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
  }
  ```
</ResponseExample>


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