Data Models - Mintlify Starter Kit

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	Paginated envelope for list results	`getTransactions()`, `getVaults()`, `getContacts()`, `getBankAccounts()`, `getSubOrgs()`
Transfer parties	The sender or receiver of a transfer	Transaction `source` and `destination`, intents
Asset and chain	An asset and the blockchain it lives on	Assets and chains
Vaults	An account that holds assets	`getVaults()`
Contacts	A saved blockchain address	`getContacts()`
Bank accounts	A saved bank account	`getBankAccounts()`
Transactions	A transfer, swap, or other on-chain or fiat operation	`getTransactions()`, webhook events
Transaction operations	One leg of a transaction workflow and its balance changes	Transaction `operations`, webhook events
Intent and quote	A payment order and its priced quote	`getQuote()`, `createTransactionFromIntent()`
Deposit instructions	Details for funding a vault or transaction	Vault and transaction deposit instructions
Fees and balances	Fee estimates and vault balances	Fee estimates, balances
Approval models	Approval messages and approve/reject results	Approvals
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 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

enum TransferPartyType {
  CONTACT = "CONTACT",
  VAULT = "VAULT",
  EXTERNAL_ADDRESS = "EXTERNAL_ADDRESS",
  EXTERNAL_BANK_ACCOUNT = "EXTERNAL_BANK_ACCOUNT",
  BANK_ACCOUNT = "BANK_ACCOUNT",
}

TransferPartyData

interface TransferPartyData {
  type: TransferPartyType | string;
  id?: string;
  name?: string;
  address?: string;
  provider?: string;
  bankDetails?: BankDetails;
  chain?: string;
  paymentRail?: string;
}

BankDetails

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

interface Asset {
  name: string;
  symbol: string;
  blockChain: string;
  logoURL?: string;
  details?: unknown;
}

ChainData

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

enum VaultType {
  EXCHANGE = "EXCHANGE",
  DEFAULT = "DEFAULT",
  GAS = "GAS",
}

Vault

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

enum ContactStatus {
  PENDING = "PENDING",
  APPROVED = "APPROVED",
  DECLINED = "DECLINED",
}

Contact

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

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

BankAccountStatus

enum BankAccountStatus {
  PENDING = "PENDING",
  APPROVED = "APPROVED",
  DECLINED = "DECLINED",
}

BankAccount

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

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

enum TransactionType {
  INCOMING = "INCOMING",
  OUTGOING = "OUTGOING",
}

TransactionCategory

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

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

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

enum TransactionOperationType {
  DEPOSIT = "DEPOSIT",
  TRADE = "TRADE",
  TRANSFER = "TRANSFER",
  WITHDRAW = "WITHDRAW",
}

TransactionOperationStatus

enum TransactionOperationStatus {
  PENDING = "PENDING",
  PROCESSING = "PROCESSING",
  COMPLETED = "COMPLETED",
  FAILED = "FAILED",
  SKIPPED = "SKIPPED",
  CANCELLED = "CANCELLED",
  REVERSED = "REVERSED",
}

TransactionOperationBalanceChange

interface TransactionOperationBalanceChange {
  party: TransferPartyData | null;
  asset: string;
  amount: string;
  chain?: string;
  paymentRail?: string;
}

TransactionOperationBalanceChanges

interface TransactionOperationBalanceChanges {
  changes: TransactionOperationBalanceChange[];
}

TransactionOperation

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

interface IntentAsset {
  asset: string;
  amount?: string | null;
  vaultId?: string;
}

TransactionIntentRequest

interface TransactionIntentRequest {
  input: IntentAsset;
  output: IntentAsset;
  source?: TransferPartyData;
  destination?: TransferPartyData;
}

GetQuoteRequest

interface GetQuoteRequest {
  intent: TransactionIntentRequest;
}

TransactionExecuteIntentRequest

interface TransactionExecuteIntentRequest {
  intent?: TransactionIntentRequest | null;
  quoteId?: string | null;
  externalId?: string;
  memo?: string;
}

Fees

interface Fees {
  amount: string;
  asset: string;
  amountInFiat?: string;
}

QuoteResponseItem

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

QuoteResponse

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

interface DepositInstructions {
  type?: TransferPartyType | string;
  paymentRail?: string;
  bankDetails?: BankDetails;
  asset?: string;
  address?: string;
  chain?: string;
  memo?: string;
}

GetVaultDepositInstructionsRequest

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

VaultDepositInstructionsResponse

interface VaultDepositInstructionsResponse {
  results: DepositInstructions[];
}

Fees and balances

FeeData

interface FeeData {
  expectedFeeInAsset: string;
  asset: string;
  expectedFeeInUSD: string;
  baseFee?: string;
  priorityFee?: string;
}

EstimatedFeeResponse

interface EstimatedFeeResponse {
  high: FeeData;
  medium: FeeData;
  low: FeeData;
}

BalanceResponse

interface BalanceResponse {
  [asset: string]: {
    [chain: string]: string;
  };
}

DetailedBalance

interface DetailedBalance {
  symbol: string;
  balance: string;
  name?: string;
  chain?: string;
  tokenAddress?: string;
  balanceInUSD?: string;
  price?: string;
}

DetailedBalanceResponse

type DetailedBalanceResponse = DetailedBalance[];

Approval models

ApprovalAction

enum ApprovalAction {
  APPROVE = "approve",
  REJECT = "reject",
  DECLINE = "reject",
}

GetApprovalMessageResponse

interface GetApprovalMessageResponse {
  approvalId: string;
  message: string;
  changeRequestId?: string;
  entityId?: string;
}

ApprovalActionResponse

interface ApprovalActionResponse {
  success: boolean;
  status?: string;
  id?: string;
  entityId?: string;
}

Webhook event envelope

WebhookEvent

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

​Models on this page

​Cursor list response

​Transfer parties

​TransferPartyType

​TransferPartyData

​BankDetails

​Asset and chain

​Asset

​ChainData

​Vaults

​VaultType

​Vault

​Contacts

​ContactStatus

​Contact

​Bank accounts

​BankAccountStatus

​BankAccount

​Transactions

​Transaction

​TransactionType

​TransactionCategory

​TransactionSubCategory

​TransactionStatus

​Transaction operations and balance changes

​TransactionOperationType

​TransactionOperationStatus

​TransactionOperationBalanceChange

​TransactionOperationBalanceChanges

​TransactionOperation

​Intent and quote

​IntentAsset

​TransactionIntentRequest

​GetQuoteRequest

​TransactionExecuteIntentRequest

​Fees

​QuoteResponseItem

​QuoteResponse

​Deposit instructions

​DepositInstructions

​GetVaultDepositInstructionsRequest

​VaultDepositInstructionsResponse

​Fees and balances

​FeeData

​EstimatedFeeResponse

​BalanceResponse

​DetailedBalance

​DetailedBalanceResponse

​Approval models

​ApprovalAction

​GetApprovalMessageResponse

​ApprovalActionResponse

​Webhook event envelope

​WebhookEvent

Models on this page

Cursor list response

Transfer parties

TransferPartyType

TransferPartyData

BankDetails

Asset and chain

Asset

ChainData

Vaults

VaultType

Vault

Contacts

ContactStatus

Contact

Bank accounts

BankAccountStatus

BankAccount

Transactions

Transaction

TransactionType

TransactionCategory

TransactionSubCategory

TransactionStatus

Transaction operations and balance changes

TransactionOperationType

TransactionOperationStatus

TransactionOperationBalanceChange

TransactionOperationBalanceChanges

TransactionOperation

Intent and quote

IntentAsset

TransactionIntentRequest

GetQuoteRequest

TransactionExecuteIntentRequest

Fees

QuoteResponseItem

QuoteResponse

Deposit instructions

DepositInstructions

GetVaultDepositInstructionsRequest

VaultDepositInstructionsResponse

Fees and balances

FeeData

EstimatedFeeResponse

BalanceResponse

DetailedBalance

DetailedBalanceResponse

Approval models

ApprovalAction

GetApprovalMessageResponse

ApprovalActionResponse

Webhook event envelope

WebhookEvent