Create a Transfer

Request example

{
  "source": { "type": "VAULT", "id": "vault_123" },
  "destination": { "type": "CONTACT", "id": "contact_456" },
  "amount": "0.50",
  "asset": "ETH",
  "blockChain": "ETHEREUM",
  "category": "TRANSFER",
  "externalId": "invoice-1001",
  "memo": "Vendor payout #1001",
  "feePayer": { "id": "vault_234" }
}

# 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/transactions/" \
  --header "Authorization: Bearer <signed JWT>" \
  --header "Api-Key: <API key>" \
  --header "Content-Type: application/json" \
  --data '{
    "source": { "type": "VAULT", "id": "vault_123" },
    "destination": { "type": "CONTACT", "id": "contact_456" },
    "amount": "0.50",
    "asset": "ETH",
    "blockChain": "ETHEREUM",
    "category": "TRANSFER",
    "externalId": "invoice-1001",
    "memo": "Vendor payout #1001",
    "feePayer": { "id": "vault_234" }
  }'

interface CreateTransferTransactionRequest {
  source: TransferPartyData;
  destination: TransferPartyData;
  amount: string;
  asset: string;
  chain: string;
  externalId?: string;
  memo?: string;
  feePayer?: { id: string };
}

createTransferTransaction(
  request: CreateTransferTransactionRequest,
): Promise<Transaction>

const tx = await apiClient.createTransferTransaction({
  source: { type: "VAULT", id: "vault_123" },
  destination: { type: "CONTACT", id: "contact_456" },
  amount: "0.50",
  asset: "ETH",
  chain: "ETHEREUM",
  externalId: "invoice-1001",
  memo: "Vendor payout #1001",
  feePayer: { id: "vault_234" },
});
console.log(tx.id, tx.status);

Response example

{
  "id": "transaction_123",
  "orgId": "org_456",
  "vaultId": "vault_123",
  "status": "PENDING",
  "transactionType": "OUTGOING",
  "category": "TRANSFER",
  "subCategory": "EXTERNAL_TRANSFER",
  "createdAt": "2026-08-04T10:40:00Z",
  "updatedAt": "2026-08-04T10:40:00Z",
  "isDeleted": false,
  "externalId": "invoice-1001",
  "memo": "Vendor payout #1001",
  "source": {
    "type": "VAULT",
    "id": "vault_123",
    "subOrgId": "sub_org_123",
    "name": "Treasury Vault"
  },
  "destination": {
    "type": "CONTACT",
    "id": "contact_456",
    "name": "Operations Wallet",
    "address": "0xAbC1234567890abcdef1234567890abcdef1234",
    "chain": "ETHEREUM"
  },
  "blockChain": "ETHEREUM",
  "asset": "ETH",
  "amount": "0.50"
}

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?: TransferPartyData;
  destination?: TransferPartyData;
  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;
}

POST /api/external/transactions/ Use a transfer when you already know the source, destination, blockchain, asset, and amount. You can estimate the network fee first. The returned status is the lifecycle source of truth.

Request body

TransferPartyData

required

Sending party.

TransferPartyData

required

Receiving party.

string

required

Decimal transfer amount.

string

required

Asset symbol.

string

required

Blockchain identifier.

string

required

Must be "TRANSFER".

string

Client reference.

string

Human-readable note.

object

Vault that pays the network fee when the chain supports sponsored fee payment.

Show Properties

string

required

Vault ID that will pay the fee.

The SDK accepts chain and serializes it as blockChain. It injects category: "TRANSFER".

Response

Returns the new Transaction. Its status is the lifecycle source of truth.

string

Transaction ID. Use it with Retrieve Transaction to track status.

string

Organization that owns the transaction.

string

Vault the transaction runs from.

string

Lifecycle status. Track it until COMPLETED, FAILED, or DECLINED. See TransactionStatus.

string

See TransactionType.

string

For example TRANSFER or CONTRACT_CALL. See TransactionCategory.

string

See TransactionSubCategory.

string

Creation timestamp (ISO 8601).

string

Last update timestamp (ISO 8601).

boolean

Whether the transaction is deleted.

string

Your own reference, if you set one.

string

Memo you attached, if any.

TransferPartyData

Where the funds come from. Which fields are present depends on type. See TransferPartyData.

Show Properties

string

VAULT, BANK_ACCOUNT, CONTACT, EXTERNAL_ADDRESS, or EXTERNAL_BANK_ACCOUNT.

string

ID of the vault, bank account, or contact.

string

Display name.

string

Wallet address, for crypto parties.

string

Blockchain, for crypto parties.

string

Payment rail, for bank parties, such as ACH.

TransferPartyData

Where the funds go. Same fields as source. See TransferPartyData.

Show Properties

string

VAULT, BANK_ACCOUNT, CONTACT, EXTERNAL_ADDRESS, or EXTERNAL_BANK_ACCOUNT.

string

ID of the vault, bank account, or contact.

string

Display name.

string

Wallet address, for crypto parties.

string

Blockchain, for crypto parties.

string

Payment rail, for bank parties, such as ACH.

string

Chain the transaction runs on.

string

Asset moved.

string

Amount as a decimal string.

Approve the transaction

New transfers return status: "PENDING" and wait for approval. Get the approval message for the transaction id, sign it with your API user’s key, then submit the approval. See Approvals. With the SDK, createTransactionWithApproval(request) creates and approves in one call. createTransferTransaction(request) only creates.

Request example

{
  "source": { "type": "VAULT", "id": "vault_123" },
  "destination": { "type": "CONTACT", "id": "contact_456" },
  "amount": "0.50",
  "asset": "ETH",
  "blockChain": "ETHEREUM",
  "category": "TRANSFER",
  "externalId": "invoice-1001",
  "memo": "Vendor payout #1001",
  "feePayer": { "id": "vault_234" }
}

# 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/transactions/" \
  --header "Authorization: Bearer <signed JWT>" \
  --header "Api-Key: <API key>" \
  --header "Content-Type: application/json" \
  --data '{
    "source": { "type": "VAULT", "id": "vault_123" },
    "destination": { "type": "CONTACT", "id": "contact_456" },
    "amount": "0.50",
    "asset": "ETH",
    "blockChain": "ETHEREUM",
    "category": "TRANSFER",
    "externalId": "invoice-1001",
    "memo": "Vendor payout #1001",
    "feePayer": { "id": "vault_234" }
  }'

interface CreateTransferTransactionRequest {
  source: TransferPartyData;
  destination: TransferPartyData;
  amount: string;
  asset: string;
  chain: string;
  externalId?: string;
  memo?: string;
  feePayer?: { id: string };
}

createTransferTransaction(
  request: CreateTransferTransactionRequest,
): Promise<Transaction>

const tx = await apiClient.createTransferTransaction({
  source: { type: "VAULT", id: "vault_123" },
  destination: { type: "CONTACT", id: "contact_456" },
  amount: "0.50",
  asset: "ETH",
  chain: "ETHEREUM",
  externalId: "invoice-1001",
  memo: "Vendor payout #1001",
  feePayer: { id: "vault_234" },
});
console.log(tx.id, tx.status);

Response example

{
  "id": "transaction_123",
  "orgId": "org_456",
  "vaultId": "vault_123",
  "status": "PENDING",
  "transactionType": "OUTGOING",
  "category": "TRANSFER",
  "subCategory": "EXTERNAL_TRANSFER",
  "createdAt": "2026-08-04T10:40:00Z",
  "updatedAt": "2026-08-04T10:40:00Z",
  "isDeleted": false,
  "externalId": "invoice-1001",
  "memo": "Vendor payout #1001",
  "source": {
    "type": "VAULT",
    "id": "vault_123",
    "subOrgId": "sub_org_123",
    "name": "Treasury Vault"
  },
  "destination": {
    "type": "CONTACT",
    "id": "contact_456",
    "name": "Operations Wallet",
    "address": "0xAbC1234567890abcdef1234567890abcdef1234",
    "chain": "ETHEREUM"
  },
  "blockChain": "ETHEREUM",
  "asset": "ETH",
  "amount": "0.50"
}

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?: TransferPartyData;
  destination?: TransferPartyData;
  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;
}

⌘I

Request example

{
  "source": { "type": "VAULT", "id": "vault_123" },
  "destination": { "type": "CONTACT", "id": "contact_456" },
  "amount": "0.50",
  "asset": "ETH",
  "blockChain": "ETHEREUM",
  "category": "TRANSFER",
  "externalId": "invoice-1001",
  "memo": "Vendor payout #1001",
  "feePayer": { "id": "vault_234" }
}

# 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/transactions/" \
  --header "Authorization: Bearer <signed JWT>" \
  --header "Api-Key: <API key>" \
  --header "Content-Type: application/json" \
  --data '{
    "source": { "type": "VAULT", "id": "vault_123" },
    "destination": { "type": "CONTACT", "id": "contact_456" },
    "amount": "0.50",
    "asset": "ETH",
    "blockChain": "ETHEREUM",
    "category": "TRANSFER",
    "externalId": "invoice-1001",
    "memo": "Vendor payout #1001",
    "feePayer": { "id": "vault_234" }
  }'

interface CreateTransferTransactionRequest {
  source: TransferPartyData;
  destination: TransferPartyData;
  amount: string;
  asset: string;
  chain: string;
  externalId?: string;
  memo?: string;
  feePayer?: { id: string };
}

createTransferTransaction(
  request: CreateTransferTransactionRequest,
): Promise<Transaction>

const tx = await apiClient.createTransferTransaction({
  source: { type: "VAULT", id: "vault_123" },
  destination: { type: "CONTACT", id: "contact_456" },
  amount: "0.50",
  asset: "ETH",
  chain: "ETHEREUM",
  externalId: "invoice-1001",
  memo: "Vendor payout #1001",
  feePayer: { id: "vault_234" },
});
console.log(tx.id, tx.status);

Response example

{
  "id": "transaction_123",
  "orgId": "org_456",
  "vaultId": "vault_123",
  "status": "PENDING",
  "transactionType": "OUTGOING",
  "category": "TRANSFER",
  "subCategory": "EXTERNAL_TRANSFER",
  "createdAt": "2026-08-04T10:40:00Z",
  "updatedAt": "2026-08-04T10:40:00Z",
  "isDeleted": false,
  "externalId": "invoice-1001",
  "memo": "Vendor payout #1001",
  "source": {
    "type": "VAULT",
    "id": "vault_123",
    "subOrgId": "sub_org_123",
    "name": "Treasury Vault"
  },
  "destination": {
    "type": "CONTACT",
    "id": "contact_456",
    "name": "Operations Wallet",
    "address": "0xAbC1234567890abcdef1234567890abcdef1234",
    "chain": "ETHEREUM"
  },
  "blockChain": "ETHEREUM",
  "asset": "ETH",
  "amount": "0.50"
}

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?: TransferPartyData;
  destination?: TransferPartyData;
  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;
}

API Basics

Approvals

Vaults

Blockchain Contacts

Bank Accounts

Assets and Chains

Sub-Orgs

Transactions

Request body

Response

Approve the transaction

​Request body

​Response

​Approve the transaction

Request body

Response

Approve the transaction