Create a Vault

Request example

{
  "vaultName": "Treasury Vault",
  "subOrgId": "sub_org_123",
  "chains": ["ETHEREUM", "POLYGON"],
  "testNetVault": false,
  "vaultGroupIds": ["vault_group_123"]
}

# 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"
    ]
  }'

interface CreateVaultRequest {
  vaultName: string;
  subOrgId?: string;
  chains?: string[];
  testNetVault?: boolean;
  vaultGroupIds?: string[];
}

createVault(request: CreateVaultRequest): Promise<Vault>

Response example

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

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;
}

POST /api/external/vaults/

Request body

string

required

Vault name. Cannot be blank. Naming it “NGN” does not set its asset; asset is not a create input.

string

Sub-org that owns the vault.

string[]

Requested wallet chains. Use identifiers from Assets and Chains.

boolean

Creates a testnet vault when supported. Default: false.

string[]

Organization-scoped vault groups to attach.

Response

Returns the new Vault. Wallet addresses can be generated after the response, so retrieve the vault until walletsGenerated is true before using them.

string

Vault ID.

string

Organization that owns the vault.

string

Sub-org that owns the vault, if any.

string

Vault name.

VaultType

DEFAULT, EXCHANGE, or GAS. See VaultType.

string | null

Currency of a multi-currency account vault, for example NGN. null for self-custody vaults.

object[]

Blockchain wallets in the vault.

Show Properties

string

Wallet ID.

string

Chain the wallet is on.

string

Wallet address. Missing until the wallet is generated.

string

Wallet public key.

boolean

Whether wallet addresses are ready. Wait for true before using wallets.

string

Creation timestamp (ISO 8601).

string

Last update timestamp (ISO 8601).

boolean

Whether the vault is deleted.

Approve the vault

Creating a vault opens a change request that your API user must approve. Call Get Approval Message with entityId set to the vault id, sign the message, and send the signature to Submit Approval Action. See Approvals for the full flow. With the SDK, approve separately or in one call:

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.

Request example

{
  "vaultName": "Treasury Vault",
  "subOrgId": "sub_org_123",
  "chains": ["ETHEREUM", "POLYGON"],
  "testNetVault": false,
  "vaultGroupIds": ["vault_group_123"]
}

# 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"
    ]
  }'

interface CreateVaultRequest {
  vaultName: string;
  subOrgId?: string;
  chains?: string[];
  testNetVault?: boolean;
  vaultGroupIds?: string[];
}

createVault(request: CreateVaultRequest): Promise<Vault>

Response example

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

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;
}

⌘I

Request example

{
  "vaultName": "Treasury Vault",
  "subOrgId": "sub_org_123",
  "chains": ["ETHEREUM", "POLYGON"],
  "testNetVault": false,
  "vaultGroupIds": ["vault_group_123"]
}

# 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"
    ]
  }'

interface CreateVaultRequest {
  vaultName: string;
  subOrgId?: string;
  chains?: string[];
  testNetVault?: boolean;
  vaultGroupIds?: string[];
}

createVault(request: CreateVaultRequest): Promise<Vault>

Response example

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

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;
}

API Basics

Approvals

Vaults

Blockchain Contacts

Bank Accounts

Assets and Chains

Sub-Orgs

Transactions

Request body

Response

Approve the vault

​Request body

​Response

​Approve the vault

Request body

Response

Approve the vault