Create a Contract Call

Request example

{
  "vaultId": "vault_123",
  "blockChain": "ETHEREUM",
  "amount": "0",
  "category": "CONTRACT_CALL",
  "data": {
    "callData": "0xa9059cbb000000000000000000000000...",
    "toAddress": "0xTokenContract1234567890abcdef"
  },
  "externalId": "contract-call-1001",
  "gasParams": {
    "feeTier": "MEDIUM"
  },
  "creationOptions": {
    "skipPreprocessSimulation": false
  }
}

# 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 '{
    "vaultId": "vault_123",
    "blockChain": "ETHEREUM",
    "amount": "0",
    "category": "CONTRACT_CALL",
    "data": {
      "callData": "0xa9059cbb000000000000000000000000...",
      "toAddress": "0xTokenContract1234567890abcdef"
    },
    "externalId": "contract-call-1001",
    "gasParams": { "feeTier": "MEDIUM" },
    "creationOptions": { "skipPreprocessSimulation": false }
  }'

const tx = await apiClient.createContractCallTransaction({
  vaultId: "vault_123",
  chain: "ETHEREUM",
  amount: "0",
  data: {
    callData: "0xa9059cbb000000000000000000000000...",
    toAddress: "0xTokenContract1234567890abcdef",
  },
  externalId: "contract-call-1001",
  gasParams: { feeTier: "MEDIUM" },
  creationOptions: { skipPreprocessSimulation: false },
});
console.log(tx.id, tx.status);

Response example

{
  "id": "transaction_contract_123",
  "orgId": "org_456",
  "vaultId": "vault_123",
  "status": "PENDING",
  "transactionType": "OUTGOING",
  "category": "CONTRACT_CALL",
  "subCategory": "CONTRACT_CALL",
  "createdAt": "2026-08-04T11:00:00Z",
  "updatedAt": "2026-08-04T11:00:00Z",
  "isDeleted": false,
  "externalId": "contract-call-1001",
  "source": {
    "type": "VAULT",
    "id": "vault_123",
    "name": "Treasury Vault"
  },
  "blockChain": "ETHEREUM",
  "amount": "0"
}

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 contract call for arbitrary contract execution. These transactions can have chain-specific data requirements and may require approval before broadcast.

Request body

string

required

Vault that signs and submits the call.

string

required

Blockchain identifier.

string

Decimal amount of native asset sent with the call.

string

required

Must be "CONTRACT_CALL".

object

Chain-specific call payload. Use one of the following shapes.

Show Shapes

{ callData: string; toAddress?: string }

Encoded call data and the target contract address.

{ canisterId: string; method: string; arg: string }

Canister ID, method name, and encoded argument.

{ messageHex: string }

Hex-encoded message to sign.

{ method: string; params: Record<string, unknown> }

Method name and parameters.

string

Client reference.

object

Gas settings for the call.

Show Properties

string

One of HIGH, MEDIUM, or LOW.

object

Creation options.

Show Properties

boolean

Set only when your integration has an explicit reason to bypass supported preprocessing or simulation.

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

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.

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.

string

Chain the transaction runs on.

string

Amount as a decimal string.

Approve the transaction

New transactions 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, call approveChangeRequest({ entityId: transaction.id, action: "approve" }) after this call.

Request example

{
  "vaultId": "vault_123",
  "blockChain": "ETHEREUM",
  "amount": "0",
  "category": "CONTRACT_CALL",
  "data": {
    "callData": "0xa9059cbb000000000000000000000000...",
    "toAddress": "0xTokenContract1234567890abcdef"
  },
  "externalId": "contract-call-1001",
  "gasParams": {
    "feeTier": "MEDIUM"
  },
  "creationOptions": {
    "skipPreprocessSimulation": false
  }
}

# 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 '{
    "vaultId": "vault_123",
    "blockChain": "ETHEREUM",
    "amount": "0",
    "category": "CONTRACT_CALL",
    "data": {
      "callData": "0xa9059cbb000000000000000000000000...",
      "toAddress": "0xTokenContract1234567890abcdef"
    },
    "externalId": "contract-call-1001",
    "gasParams": { "feeTier": "MEDIUM" },
    "creationOptions": { "skipPreprocessSimulation": false }
  }'

const tx = await apiClient.createContractCallTransaction({
  vaultId: "vault_123",
  chain: "ETHEREUM",
  amount: "0",
  data: {
    callData: "0xa9059cbb000000000000000000000000...",
    toAddress: "0xTokenContract1234567890abcdef",
  },
  externalId: "contract-call-1001",
  gasParams: { feeTier: "MEDIUM" },
  creationOptions: { skipPreprocessSimulation: false },
});
console.log(tx.id, tx.status);

Response example

{
  "id": "transaction_contract_123",
  "orgId": "org_456",
  "vaultId": "vault_123",
  "status": "PENDING",
  "transactionType": "OUTGOING",
  "category": "CONTRACT_CALL",
  "subCategory": "CONTRACT_CALL",
  "createdAt": "2026-08-04T11:00:00Z",
  "updatedAt": "2026-08-04T11:00:00Z",
  "isDeleted": false,
  "externalId": "contract-call-1001",
  "source": {
    "type": "VAULT",
    "id": "vault_123",
    "name": "Treasury Vault"
  },
  "blockChain": "ETHEREUM",
  "amount": "0"
}

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

{
  "vaultId": "vault_123",
  "blockChain": "ETHEREUM",
  "amount": "0",
  "category": "CONTRACT_CALL",
  "data": {
    "callData": "0xa9059cbb000000000000000000000000...",
    "toAddress": "0xTokenContract1234567890abcdef"
  },
  "externalId": "contract-call-1001",
  "gasParams": {
    "feeTier": "MEDIUM"
  },
  "creationOptions": {
    "skipPreprocessSimulation": false
  }
}

# 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 '{
    "vaultId": "vault_123",
    "blockChain": "ETHEREUM",
    "amount": "0",
    "category": "CONTRACT_CALL",
    "data": {
      "callData": "0xa9059cbb000000000000000000000000...",
      "toAddress": "0xTokenContract1234567890abcdef"
    },
    "externalId": "contract-call-1001",
    "gasParams": { "feeTier": "MEDIUM" },
    "creationOptions": { "skipPreprocessSimulation": false }
  }'

const tx = await apiClient.createContractCallTransaction({
  vaultId: "vault_123",
  chain: "ETHEREUM",
  amount: "0",
  data: {
    callData: "0xa9059cbb000000000000000000000000...",
    toAddress: "0xTokenContract1234567890abcdef",
  },
  externalId: "contract-call-1001",
  gasParams: { feeTier: "MEDIUM" },
  creationOptions: { skipPreprocessSimulation: false },
});
console.log(tx.id, tx.status);

Response example

{
  "id": "transaction_contract_123",
  "orgId": "org_456",
  "vaultId": "vault_123",
  "status": "PENDING",
  "transactionType": "OUTGOING",
  "category": "CONTRACT_CALL",
  "subCategory": "CONTRACT_CALL",
  "createdAt": "2026-08-04T11:00:00Z",
  "updatedAt": "2026-08-04T11:00:00Z",
  "isDeleted": false,
  "externalId": "contract-call-1001",
  "source": {
    "type": "VAULT",
    "id": "vault_123",
    "name": "Treasury Vault"
  },
  "blockChain": "ETHEREUM",
  "amount": "0"
}

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

Create a Contract Call

Request body

Response

Approve the transaction

​Request body

​Response

​Approve the transaction

Request body

Response

Approve the transaction