Execute a Trade Quote

Request example

{
  "intent": null,
  "quoteId": "quote_lp_best_3043",
  "externalId": "trade-usdt-usd-3043",
  "memo": "Sell 10000 USDT for USD"
}

# 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/intent/create/" \
  --header "Authorization: Bearer <signed JWT>" \
  --header "Api-Key: <API key>" \
  --header "Content-Type: application/json" \
  --data '{
    "intent": null,
    "quoteId": "quote_lp_best_3043",
    "externalId": "trade-usdt-usd-3043",
    "memo": "Sell 10000 USDT for USD"
  }'

const transaction = await apiClient.createTransactionFromIntent({
  quoteId: "quote_lp_best_3043",
  externalId: "trade-usdt-usd-3043",
  memo: "Sell 10000 USDT for USD",
});
console.log(transaction.id, transaction.status);

Response example

{
  "id": "transaction_trade_3043",
  "orgId": "org_456",
  "vaultId": "vault_gsr_lp",
  "status": "PENDING",
  "transactionType": "OUTGOING",
  "createdAt": "2026-09-30T10:00:05Z",
  "updatedAt": "2026-09-30T10:00:05Z",
  "isDeleted": false,
  "externalId": "trade-usdt-usd-3043",
  "memo": "Sell 10000 USDT for USD",
  "source": { "type": "VAULT", "id": "vault_gsr_lp" },
  "destination": { "type": "VAULT", "id": "vault_gsr_lp" },
  "balanceChanges": {
    "changes": [
      {
        "party": { "type": "VAULT", "id": "vault_gsr_lp" },
        "asset": "USDT",
        "amount": "-10000.00"
      },
      {
        "party": { "type": "VAULT", "id": "vault_gsr_lp" },
        "asset": "USD",
        "amount": "9997.00"
      }
    ]
  },
  "quoteResponse": {
    "quoteId": "quote_lp_best_3043",
    "rate": "1.00030009",
    "fees": { "amount": "0", "asset": "USDT" },
    "input": { "asset": "USDT", "amount": "10000.00" },
    "output": { "asset": "USD", "amount": "9997.00" },
    "source": { "type": "VAULT", "id": "vault_gsr_lp" },
    "destination": { "type": "VAULT", "id": "vault_gsr_lp" },
    "expiresAt": "2026-09-30T10:00:30+00:00"
  },
  "depositInstructions": {
    "type": "EXTERNAL_ADDRESS",
    "asset": "USDT",
    "chain": "ETHEREUM",
    "address": "<DEPOSIT_ADDRESS_FROM_RESPONSE>"
  }
}

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/intent/create/ Example: executes the trade quote quote_lp_best_3043, selling 10,000 USDT for 9,997 USD.

Request body

string

required

The quoteId returned by Get Quote.

null

Send null when executing a quote. Do not repeat the quote intent.

string

Client reference.

string

Human-readable note.

Response

Returns HTTP 201 with a full Transaction. Optional fields depend on the payment route and status.

string

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

string

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

QuoteResponseItem

The executed quote, including its input, output, source, destination, and expiresAt. See QuoteResponseItem.

TransferPartyData

Where the funds come from, as a TransferPartyData. Which fields are present depends on type.

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.

TransactionOperationBalanceChanges | null

Aggregate balance movements across the transaction, when present: the input asset debited and the output asset credited. See TransactionOperationBalanceChanges.

Show Properties

TransactionOperationBalanceChange[]

One entry per party and asset. See TransactionOperationBalanceChange.

Show Properties

TransferPartyData | null

Party whose balance changed. Same fields as source. See TransferPartyData.

string

Asset symbol.

string

Signed decimal string: negative for a debit, positive for a credit.

string

Blockchain, for crypto movements.

string

Payment rail, for fiat movements.

DepositInstructions

Present when funding is required. Use the returned details exactly. See DepositInstructions.

Executing a quote creates a transaction in PENDING that waits for approval. Get the approval message for the transaction id, sign it, then submit the approval. The SDK’s createTransactionFromIntent() does this for you and returns the updated transaction. See Approvals.

Request example

{
  "intent": null,
  "quoteId": "quote_lp_best_3043",
  "externalId": "trade-usdt-usd-3043",
  "memo": "Sell 10000 USDT for USD"
}

# 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/intent/create/" \
  --header "Authorization: Bearer <signed JWT>" \
  --header "Api-Key: <API key>" \
  --header "Content-Type: application/json" \
  --data '{
    "intent": null,
    "quoteId": "quote_lp_best_3043",
    "externalId": "trade-usdt-usd-3043",
    "memo": "Sell 10000 USDT for USD"
  }'

const transaction = await apiClient.createTransactionFromIntent({
  quoteId: "quote_lp_best_3043",
  externalId: "trade-usdt-usd-3043",
  memo: "Sell 10000 USDT for USD",
});
console.log(transaction.id, transaction.status);

Response example

{
  "id": "transaction_trade_3043",
  "orgId": "org_456",
  "vaultId": "vault_gsr_lp",
  "status": "PENDING",
  "transactionType": "OUTGOING",
  "createdAt": "2026-09-30T10:00:05Z",
  "updatedAt": "2026-09-30T10:00:05Z",
  "isDeleted": false,
  "externalId": "trade-usdt-usd-3043",
  "memo": "Sell 10000 USDT for USD",
  "source": { "type": "VAULT", "id": "vault_gsr_lp" },
  "destination": { "type": "VAULT", "id": "vault_gsr_lp" },
  "balanceChanges": {
    "changes": [
      {
        "party": { "type": "VAULT", "id": "vault_gsr_lp" },
        "asset": "USDT",
        "amount": "-10000.00"
      },
      {
        "party": { "type": "VAULT", "id": "vault_gsr_lp" },
        "asset": "USD",
        "amount": "9997.00"
      }
    ]
  },
  "quoteResponse": {
    "quoteId": "quote_lp_best_3043",
    "rate": "1.00030009",
    "fees": { "amount": "0", "asset": "USDT" },
    "input": { "asset": "USDT", "amount": "10000.00" },
    "output": { "asset": "USD", "amount": "9997.00" },
    "source": { "type": "VAULT", "id": "vault_gsr_lp" },
    "destination": { "type": "VAULT", "id": "vault_gsr_lp" },
    "expiresAt": "2026-09-30T10:00:30+00:00"
  },
  "depositInstructions": {
    "type": "EXTERNAL_ADDRESS",
    "asset": "USDT",
    "chain": "ETHEREUM",
    "address": "<DEPOSIT_ADDRESS_FROM_RESPONSE>"
  }
}

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

{
  "intent": null,
  "quoteId": "quote_lp_best_3043",
  "externalId": "trade-usdt-usd-3043",
  "memo": "Sell 10000 USDT for USD"
}

# 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/intent/create/" \
  --header "Authorization: Bearer <signed JWT>" \
  --header "Api-Key: <API key>" \
  --header "Content-Type: application/json" \
  --data '{
    "intent": null,
    "quoteId": "quote_lp_best_3043",
    "externalId": "trade-usdt-usd-3043",
    "memo": "Sell 10000 USDT for USD"
  }'

const transaction = await apiClient.createTransactionFromIntent({
  quoteId: "quote_lp_best_3043",
  externalId: "trade-usdt-usd-3043",
  memo: "Sell 10000 USDT for USD",
});
console.log(transaction.id, transaction.status);

Response example

{
  "id": "transaction_trade_3043",
  "orgId": "org_456",
  "vaultId": "vault_gsr_lp",
  "status": "PENDING",
  "transactionType": "OUTGOING",
  "createdAt": "2026-09-30T10:00:05Z",
  "updatedAt": "2026-09-30T10:00:05Z",
  "isDeleted": false,
  "externalId": "trade-usdt-usd-3043",
  "memo": "Sell 10000 USDT for USD",
  "source": { "type": "VAULT", "id": "vault_gsr_lp" },
  "destination": { "type": "VAULT", "id": "vault_gsr_lp" },
  "balanceChanges": {
    "changes": [
      {
        "party": { "type": "VAULT", "id": "vault_gsr_lp" },
        "asset": "USDT",
        "amount": "-10000.00"
      },
      {
        "party": { "type": "VAULT", "id": "vault_gsr_lp" },
        "asset": "USD",
        "amount": "9997.00"
      }
    ]
  },
  "quoteResponse": {
    "quoteId": "quote_lp_best_3043",
    "rate": "1.00030009",
    "fees": { "amount": "0", "asset": "USDT" },
    "input": { "asset": "USDT", "amount": "10000.00" },
    "output": { "asset": "USD", "amount": "9997.00" },
    "source": { "type": "VAULT", "id": "vault_gsr_lp" },
    "destination": { "type": "VAULT", "id": "vault_gsr_lp" },
    "expiresAt": "2026-09-30T10:00:30+00:00"
  },
  "depositInstructions": {
    "type": "EXTERNAL_ADDRESS",
    "asset": "USDT",
    "chain": "ETHEREUM",
    "address": "<DEPOSIT_ADDRESS_FROM_RESPONSE>"
  }
}

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

Accounts

Sub-Orgs

Transactions

Request body

Response

​Request body

​Response

Request body

Response