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

# Data Models

> TypeScript data models used by the PrimeVault API and JavaScript SDK, including vaults, contacts, bank accounts, transactions, intents, quotes, and webhooks.

These models mirror the public types and serializers used by the current `@primevault/js-api-sdk`. Optional properties are marked with `?`. Unless explicitly stated otherwise, IDs and decimal amounts are strings.

## Models on this page

| Model | What it represents | Used by |
| - | - | - |
| [Cursor list response](#cursor-list-response) | Paginated envelope for list results | `getTransactions()`, `getVaults()`, `getContacts()`, `getBankAccounts()`, `getSubOrgs()` |
| [Transfer parties](#transfer-parties) | The sender or receiver of a transfer | Transaction `source` and `destination`, intents |
| [Asset and chain](#asset-and-chain) | An asset and the blockchain it lives on | Assets and chains |
| [Vaults](#vaults) | An account that holds assets | `getVaults()` |
| [Contacts](#contacts) | A saved blockchain address | `getContacts()` |
| [Bank accounts](#bank-accounts) | A saved bank account | `getBankAccounts()` |
| [Transactions](#transactions) | A transfer, swap, or other on-chain or fiat operation | `getTransactions()`, webhook events |
| [Transaction operations](#transaction-operations-and-balance-changes) | One leg of a transaction workflow and its balance changes | Transaction `operations`, webhook events |
| [Intent and quote](#intent-and-quote) | A payment order and its priced quote | `getQuote()`, `createTransactionFromIntent()` |
| [Deposit instructions](#deposit-instructions) | Details for funding a vault or transaction | Vault and transaction deposit instructions |
| [Fees and balances](#fees-and-balances) | Fee estimates and vault balances | Fee estimates, balances |
| [Approval models](#approval-models) | Approval messages and approve/reject results | Approvals |
| [Webhook event envelope](#webhook-event-envelope) | The payload wrapper for webhook events | Webhooks |

## Cursor list response

Transaction, vault, contact, and bank-account list methods return the same cursor envelope. See [Cursor response](/api-basics/filtering-and-pagination#cursor-response) on Filtering and Pagination for its fields and an example.

## Transfer parties

| Party type | Identification |
| - | - |
| `VAULT`, `CONTACT`, `BANK_ACCOUNT` | Use the organization-scoped resource `id`. |
| `EXTERNAL_ADDRESS` | Use `address` and `chain`; do not put the address in `id`. |
| `EXTERNAL_BANK_ACCOUNT` | Use the applicable `bankDetails` and payment-rail fields. |

A party is the sender or receiver. Its `id` identifies that endpoint; `input.vaultId` and `output.vaultId` select the fiat accounts. Use IDs from your organization. Parties do not accept `subOrgId`.

### TransferPartyType

```typescript expandable theme={null}
enum TransferPartyType {
  CONTACT = "CONTACT",
  VAULT = "VAULT",
  EXTERNAL_ADDRESS = "EXTERNAL_ADDRESS",
  EXTERNAL_BANK_ACCOUNT = "EXTERNAL_BANK_ACCOUNT",
  BANK_ACCOUNT = "BANK_ACCOUNT",
}
```

### TransferPartyData

```typescript expandable theme={null}
interface TransferPartyData {
  type: TransferPartyType | string;
  id?: string;
  name?: string;
  address?: string;
  provider?: string;
  bankDetails?: BankDetails;
  chain?: string;
  paymentRail?: string;
}
```

### BankDetails

```typescript expandable theme={null}
interface BankDetails {
  bankAccountId?: string;
  bankName?: string;
  bankCode?: string;
  beneficiaryName?: string;
  accountName?: string;
  accountNumber?: string;
  accountNumberMasked?: string;
  routingNumber?: string;
  paymentRail?: string;
  bankAddress?: string;
  beneficiaryAddress?: string;
  swiftCode?: string;
  swiftBic?: string;
  iban?: string;
  country?: string;
}
```

## Asset and chain

`details` is chain-specific. Use `symbol` plus `blockChain` to identify an asset representation.

### Asset

```typescript theme={null}
interface Asset {
  name: string;
  symbol: string;
  blockChain: string;
  logoURL?: string;
  details?: unknown;
}
```

### ChainData

```typescript theme={null}
interface ChainData {
  value: string;
  label: string;
}
```

## Vaults

A vault is like an account. `asset: "NGN"` means it holds NGN. Set `input.vaultId` or `output.vaultId` to that account's ID. A null or missing `asset` does not identify a currency account.

`walletsGenerated` describes blockchain-wallet readiness after creation and approval; use returned bank deposit instructions for fiat funding.

### VaultType

```typescript expandable theme={null}
enum VaultType {
  EXCHANGE = "EXCHANGE",
  DEFAULT = "DEFAULT",
  GAS = "GAS",
}
```

### Vault

```typescript expandable 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;
}
```

## Contacts

### ContactStatus

```typescript expandable theme={null}
enum ContactStatus {
  PENDING = "PENDING",
  APPROVED = "APPROVED",
  DECLINED = "DECLINED",
}
```

### Contact

```typescript expandable theme={null}
interface Contact {
  id: string;
  orgId: string;
  subOrgId?: string;
  name: string;
  blockChain: string;
  address: string;
  status: ContactStatus;
  isSmartContractAddress: boolean;
  tags?: string[];
  createdById: string;
  isSanctioned: boolean;
  externalId?: string;
  createdAt: string;
  updatedAt: string;
  isDeleted: boolean;
  assetList?: string[];
}
```

## Bank accounts

<Warning>
  Bank-account fields can contain sensitive financial data. Avoid including them in application logs or analytics payloads.
</Warning>

### BankAccountStatus

```typescript expandable theme={null}
enum BankAccountStatus {
  PENDING = "PENDING",
  APPROVED = "APPROVED",
  DECLINED = "DECLINED",
}
```

### BankAccount

```typescript expandable theme={null}
interface BankAccount {
  id: string;
  orgId: string;
  subOrgId?: string;
  orgEntityId: string;
  createdById: string;
  createdAt: string;
  updatedAt: string;
  isDeleted: boolean;
  status: BankAccountStatus;
  accountNumber?: string;
  accountName?: string;
  routingNumber?: string;
  clientBankAccountId?: string;
  paymentMethod?: string;
  bankName?: string;
  streetLine?: string;
  city?: string;
  state?: string;
  postalCode?: string;
  country?: string;
}
```

## Transactions

### Transaction

```typescript expandable theme={null}
interface Transaction {
  id: string;
  orgId: string;
  vaultId: string;
  status: TransactionStatus | string;
  transactionType: TransactionType | string;
  category: TransactionCategory | string;
  subCategory: TransactionSubCategory | string;
  createdAt: string;
  updatedAt: string;
  isDeleted: boolean;
  amount: string;

  txHash?: string;
  error?: string;
  externalId?: string;
  createdById?: string;
  fees?: Fees;
  memo?: string;
  txnSignature?: string;
  txnSignatureData?: Record<string, unknown>;
  output?: TransactionOutput;
  amountInUSD?: string;
  nonce?: number;
  dAppId?: string;
  source?: TransactionSourceData;
  destination?: TransactionSourceData;
  quoteResponse?: QuoteResponseItem;
  depositInstructions?: DepositInstructions;
  operations?: TransactionOperation[];
  balanceChanges?: TransactionOperationBalanceChanges | null;
  blockChain?: string;
  asset?: string;

  /** Deprecated: use destination.address. */
  toAddress?: string;
  /** Deprecated: use destination.name. */
  toAddressName?: string;
  /** Deprecated: use destination.id. */
  toVaultId?: string;
  /** Deprecated: use source.address. */
  sourceAddress?: string;
}
```

### TransactionType

```typescript expandable theme={null}
enum TransactionType {
  INCOMING = "INCOMING",
  OUTGOING = "OUTGOING",
}
```

### TransactionCategory

```typescript expandable theme={null}
enum TransactionCategory {
  TRANSFER = "TRANSFER",
  SWAP = "SWAP",
  TOKEN_TRANSFER = "TOKEN_TRANSFER",
  TOKEN_APPROVAL = "TOKEN_APPROVAL",
  CONTRACT_CALL = "CONTRACT_CALL",
  STAKE = "STAKE",
  REVOKE_TOKEN_ALLOWANCE = "REVOKE_TOKEN_ALLOWANCE",
  RAMP = "RAMP",
  FX = "FX",
  DELEGATE_RESOURCE = "DELEGATE_RESOURCE",
}
```

### TransactionSubCategory

```typescript expandable theme={null}
enum TransactionSubCategory {
  INCOMING_TRANSFER = "INCOMING_TRANSFER",
  EXTERNAL_TRANSFER = "EXTERNAL_TRANSFER",
  INTERNAL_TRANSFER = "INTERNAL_TRANSFER",
  LIMIT_TRADE = "LIMIT_TRADE",
  MARKET_TRADE = "MARKET_TRADE",
  APPROVE_TOKEN_ALLOWANCE = "APPROVE_TOKEN_ALLOWANCE",
  CUSTOM_MESSAGE = "CUSTOM_MESSAGE",
  CONTRACT_CALL = "CONTRACT_CALL",
  STAKE = "STAKE",
  UNSTAKE = "UNSTAKE",
  CLAIM = "CLAIM",
  ON_RAMP = "ON_RAMP",
  OFF_RAMP = "OFF_RAMP",
}
```

### TransactionStatus

```typescript expandable theme={null}
enum TransactionStatus {
  DRAFT = "DRAFT",
  PENDING = "PENDING",
  APPROVED = "APPROVED",
  COMPLETED = "COMPLETED",
  FAILED = "FAILED",
  DECLINED = "DECLINED",
  SUBMITTED = "SUBMITTED",
  SIGNED = "SIGNED",
  WAITING_CONFIRMATION = "WAITING_CONFIRMATION",
}
```

## Transaction operations and balance changes

Use operation `sequence` to preserve workflow order. Operation-level `balanceChanges` describes that leg; top-level transaction `balanceChanges` describes the aggregate transaction view when present.

### TransactionOperationType

```typescript expandable theme={null}
enum TransactionOperationType {
  DEPOSIT = "DEPOSIT",
  TRADE = "TRADE",
  TRANSFER = "TRANSFER",
  WITHDRAW = "WITHDRAW",
}
```

### TransactionOperationStatus

```typescript expandable theme={null}
enum TransactionOperationStatus {
  PENDING = "PENDING",
  PROCESSING = "PROCESSING",
  COMPLETED = "COMPLETED",
  FAILED = "FAILED",
  SKIPPED = "SKIPPED",
  CANCELLED = "CANCELLED",
  REVERSED = "REVERSED",
}
```

### TransactionOperationBalanceChange

```typescript expandable theme={null}
interface TransactionOperationBalanceChange {
  party: TransferPartyData | null;
  asset: string;
  amount: string;
  chain?: string;
  paymentRail?: string;
}
```

### TransactionOperationBalanceChanges

```typescript expandable theme={null}
interface TransactionOperationBalanceChanges {
  changes: TransactionOperationBalanceChange[];
}
```

### TransactionOperation

```typescript expandable theme={null}
interface TransactionOperation {
  source: TransferPartyData | null;
  destination: TransferPartyData | null;
  balanceChanges: TransactionOperationBalanceChanges | null;
  sequence: number;
  type: TransactionOperationType | string;
  status: TransactionOperationStatus | string;
  provider?: string;
}
```

## Intent and quote

Think of an intent as a payment order: `input` is what you spend; `output` is what you receive. For a quote, supply both assets and exactly one amount, as a decimal string. Set `chain` or `paymentRail` on the source or destination.

Get a quote with `getQuote({ intent })`, then execute its `quoteId` with `createTransactionFromIntent({ quoteId, externalId, memo })`. Quotes may include input and output amounts. Do not send `category`, `routeAccounts`, or `subOrgId`. Omitted fields stay omitted; quote-only execution sends `intent: null`.

### IntentAsset

```typescript expandable theme={null}
interface IntentAsset {
  asset: string;
  amount?: string | null;
  vaultId?: string;
}
```

### TransactionIntentRequest

```typescript expandable theme={null}
interface TransactionIntentRequest {
  input: IntentAsset;
  output: IntentAsset;
  source?: TransferPartyData;
  destination?: TransferPartyData;
}
```

### GetQuoteRequest

```typescript expandable theme={null}
interface GetQuoteRequest {
  intent: TransactionIntentRequest;
}
```

### TransactionExecuteIntentRequest

```typescript expandable theme={null}
interface TransactionExecuteIntentRequest {
  intent?: TransactionIntentRequest | null;
  quoteId?: string | null;
  externalId?: string;
  memo?: string;
}
```

### Fees

```typescript expandable theme={null}
interface Fees {
  amount: string;
  asset: string;
  amountInFiat?: string;
}
```

### QuoteResponseItem

```typescript expandable theme={null}
interface QuoteResponseItem {
  quoteId: string;
  rate?: string | null;
  fees?: Fees | null;
  input?: IntentAsset;
  output?: IntentAsset;
  source?: TransferPartyData;
  destination?: TransferPartyData;
  expiresAt?: string;
}
```

### QuoteResponse

```typescript expandable theme={null}
interface QuoteResponse {
  quotes: QuoteResponseItem[];
}
```

## Deposit instructions

Deposit instructions are like bank transfer details. Request `asset` plus exactly one of `paymentRail` or `chain`. Vault instructions return a `results` list; transaction instructions return one optional object. Quotes do not include them. Use the returned details exactly.

### DepositInstructions

```typescript theme={null}
interface DepositInstructions {
  type?: TransferPartyType | string;
  paymentRail?: string;
  bankDetails?: BankDetails;
  asset?: string;
  address?: string;
  chain?: string;
  memo?: string;
}
```

### GetVaultDepositInstructionsRequest

```typescript theme={null}
type GetVaultDepositInstructionsRequest = {
  asset: string;
} & (
  | { chain: string; paymentRail?: never }
  | { chain?: never; paymentRail: string }
);
```

### VaultDepositInstructionsResponse

```typescript theme={null}
interface VaultDepositInstructionsResponse {
  results: DepositInstructions[];
}
```

## Fees and balances

### FeeData

```typescript expandable theme={null}
interface FeeData {
  expectedFeeInAsset: string;
  asset: string;
  expectedFeeInUSD: string;
  baseFee?: string;
  priorityFee?: string;
}
```

### EstimatedFeeResponse

```typescript expandable theme={null}
interface EstimatedFeeResponse {
  high: FeeData;
  medium: FeeData;
  low: FeeData;
}
```

### BalanceResponse

```typescript expandable theme={null}
interface BalanceResponse {
  [asset: string]: {
    [chain: string]: string;
  };
}
```

### DetailedBalance

```typescript expandable theme={null}
interface DetailedBalance {
  symbol: string;
  balance: string;
  name?: string;
  chain?: string;
  tokenAddress?: string;
  balanceInUSD?: string;
  price?: string;
}
```

### DetailedBalanceResponse

```typescript expandable theme={null}
type DetailedBalanceResponse = DetailedBalance[];
```

## Approval models

### ApprovalAction

```typescript theme={null}
enum ApprovalAction {
  APPROVE = "approve",
  REJECT = "reject",
  DECLINE = "reject",
}
```

### GetApprovalMessageResponse

```typescript theme={null}
interface GetApprovalMessageResponse {
  approvalId: string;
  message: string;
  changeRequestId?: string;
  entityId?: string;
}
```

### ApprovalActionResponse

```typescript theme={null}
interface ApprovalActionResponse {
  success: boolean;
  status?: string;
  id?: string;
  entityId?: string;
}
```

## Webhook event envelope

### WebhookEvent

```typescript theme={null}
interface WebhookEvent {
  event:
    | "TRANSACTION_STATUS_CHANGED"
    | "TRANSACTION_OPERATION_STATUS_CHANGED";
  version: "2.0.0";
  eventId: string;
  data: {
    transaction?: Transaction;
    transactionOperation?: TransactionOperation;
  };
}
```


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