Execute an FX Quote

Request example

{
  "intent": null,
  "quoteId": "quote_fx_invoice_1042",
  "externalId": "supplier-invoice-1042",
  "memo": "Pay USD 10000 supplier invoice from NGN account"
}

# 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_fx_invoice_1042",
    "externalId": "supplier-invoice-1042",
    "memo": "Pay USD 10000 supplier invoice from NGN account"
  }'

const payment = await apiClient.createTransactionFromIntent({
  quoteId: "quote_fx_invoice_1042",
  externalId: "supplier-invoice-1042",
  memo: "Pay USD 10000 supplier invoice from NGN account",
});
console.log(payment.id, payment.status);

{
  "id": "transaction_fx_invoice_1042",
  "orgId": "org_456",
  "vaultId": "vault_ngn_business",
  "status": "PENDING",
  "transactionType": "OUTGOING",
  "category": "FX",
  "createdAt": "2026-08-04T10:40:00Z",
  "updatedAt": "2026-08-04T10:40:00Z",
  "isDeleted": false,
  "externalId": "supplier-invoice-1042",
  "memo": "Pay USD 10000 supplier invoice from NGN account",
  "source": { "type": "BANK_ACCOUNT", "id": "bank_account_ngn_business", "paymentRail": "NIP" },
  "destination": { "type": "BANK_ACCOUNT", "id": "bank_account_usd_supplier", "paymentRail": "ACH" },
  "balanceChanges": {
    "changes": [
      {
        "party": { "type": "BANK_ACCOUNT", "id": "bank_account_ngn_business" },
        "asset": "NGN",
        "amount": "-15000000.00",
        "paymentRail": "NIP"
      },
      {
        "party": { "type": "BANK_ACCOUNT", "id": "bank_account_usd_supplier" },
        "asset": "USD",
        "amount": "10000.00",
        "paymentRail": "ACH"
      }
    ]
  },
  "fees": {
    "amount": "22500.00",
    "asset": "NGN"
  },
  "quoteResponse": {
    "quoteId": "quote_fx_invoice_1042",
    "fees": { "amount": "22500.00", "asset": "NGN" },
    "input": { "asset": "NGN", "amount": "15000000.00", "vaultId": "vault_ngn_business" },
    "output": { "asset": "USD", "amount": "10000.00", "vaultId": "vault_usd_settlement" },
    "source": { "type": "BANK_ACCOUNT", "id": "bank_account_ngn_business", "paymentRail": "NIP" },
    "destination": { "type": "BANK_ACCOUNT", "id": "bank_account_usd_supplier", "paymentRail": "ACH" },
    "expiresAt": "2026-09-30T10:00:30+00:00"
  },
  "depositInstructions": {
    "type": "BANK_ACCOUNT",
    "paymentRail": "NIP",
    "bankDetails": {
      "bankName": "Example Settlement Bank",
      "beneficiaryName": "Example settlement beneficiary",
      "accountNumber": "<ACCOUNT_NUMBER_FROM_RESPONSE>"
    },
    "asset": "NGN",
    "memo": "<PAYMENT_REFERENCE_FROM_RESPONSE>"
  }
}

POST /api/external/transactions/intent/create/ Example: executes the FX quote quote_fx_invoice_1042, spending 15,000,000 NGN to pay a 10,000 USD supplier invoice.

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 exact bank details and reference returned. 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_fx_invoice_1042",
  "externalId": "supplier-invoice-1042",
  "memo": "Pay USD 10000 supplier invoice from NGN account"
}

# 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_fx_invoice_1042",
    "externalId": "supplier-invoice-1042",
    "memo": "Pay USD 10000 supplier invoice from NGN account"
  }'

const payment = await apiClient.createTransactionFromIntent({
  quoteId: "quote_fx_invoice_1042",
  externalId: "supplier-invoice-1042",
  memo: "Pay USD 10000 supplier invoice from NGN account",
});
console.log(payment.id, payment.status);

{
  "id": "transaction_fx_invoice_1042",
  "orgId": "org_456",
  "vaultId": "vault_ngn_business",
  "status": "PENDING",
  "transactionType": "OUTGOING",
  "category": "FX",
  "createdAt": "2026-08-04T10:40:00Z",
  "updatedAt": "2026-08-04T10:40:00Z",
  "isDeleted": false,
  "externalId": "supplier-invoice-1042",
  "memo": "Pay USD 10000 supplier invoice from NGN account",
  "source": { "type": "BANK_ACCOUNT", "id": "bank_account_ngn_business", "paymentRail": "NIP" },
  "destination": { "type": "BANK_ACCOUNT", "id": "bank_account_usd_supplier", "paymentRail": "ACH" },
  "balanceChanges": {
    "changes": [
      {
        "party": { "type": "BANK_ACCOUNT", "id": "bank_account_ngn_business" },
        "asset": "NGN",
        "amount": "-15000000.00",
        "paymentRail": "NIP"
      },
      {
        "party": { "type": "BANK_ACCOUNT", "id": "bank_account_usd_supplier" },
        "asset": "USD",
        "amount": "10000.00",
        "paymentRail": "ACH"
      }
    ]
  },
  "fees": {
    "amount": "22500.00",
    "asset": "NGN"
  },
  "quoteResponse": {
    "quoteId": "quote_fx_invoice_1042",
    "fees": { "amount": "22500.00", "asset": "NGN" },
    "input": { "asset": "NGN", "amount": "15000000.00", "vaultId": "vault_ngn_business" },
    "output": { "asset": "USD", "amount": "10000.00", "vaultId": "vault_usd_settlement" },
    "source": { "type": "BANK_ACCOUNT", "id": "bank_account_ngn_business", "paymentRail": "NIP" },
    "destination": { "type": "BANK_ACCOUNT", "id": "bank_account_usd_supplier", "paymentRail": "ACH" },
    "expiresAt": "2026-09-30T10:00:30+00:00"
  },
  "depositInstructions": {
    "type": "BANK_ACCOUNT",
    "paymentRail": "NIP",
    "bankDetails": {
      "bankName": "Example Settlement Bank",
      "beneficiaryName": "Example settlement beneficiary",
      "accountNumber": "<ACCOUNT_NUMBER_FROM_RESPONSE>"
    },
    "asset": "NGN",
    "memo": "<PAYMENT_REFERENCE_FROM_RESPONSE>"
  }
}

⌘I

Request example

{
  "intent": null,
  "quoteId": "quote_fx_invoice_1042",
  "externalId": "supplier-invoice-1042",
  "memo": "Pay USD 10000 supplier invoice from NGN account"
}

# 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_fx_invoice_1042",
    "externalId": "supplier-invoice-1042",
    "memo": "Pay USD 10000 supplier invoice from NGN account"
  }'

const payment = await apiClient.createTransactionFromIntent({
  quoteId: "quote_fx_invoice_1042",
  externalId: "supplier-invoice-1042",
  memo: "Pay USD 10000 supplier invoice from NGN account",
});
console.log(payment.id, payment.status);

{
  "id": "transaction_fx_invoice_1042",
  "orgId": "org_456",
  "vaultId": "vault_ngn_business",
  "status": "PENDING",
  "transactionType": "OUTGOING",
  "category": "FX",
  "createdAt": "2026-08-04T10:40:00Z",
  "updatedAt": "2026-08-04T10:40:00Z",
  "isDeleted": false,
  "externalId": "supplier-invoice-1042",
  "memo": "Pay USD 10000 supplier invoice from NGN account",
  "source": { "type": "BANK_ACCOUNT", "id": "bank_account_ngn_business", "paymentRail": "NIP" },
  "destination": { "type": "BANK_ACCOUNT", "id": "bank_account_usd_supplier", "paymentRail": "ACH" },
  "balanceChanges": {
    "changes": [
      {
        "party": { "type": "BANK_ACCOUNT", "id": "bank_account_ngn_business" },
        "asset": "NGN",
        "amount": "-15000000.00",
        "paymentRail": "NIP"
      },
      {
        "party": { "type": "BANK_ACCOUNT", "id": "bank_account_usd_supplier" },
        "asset": "USD",
        "amount": "10000.00",
        "paymentRail": "ACH"
      }
    ]
  },
  "fees": {
    "amount": "22500.00",
    "asset": "NGN"
  },
  "quoteResponse": {
    "quoteId": "quote_fx_invoice_1042",
    "fees": { "amount": "22500.00", "asset": "NGN" },
    "input": { "asset": "NGN", "amount": "15000000.00", "vaultId": "vault_ngn_business" },
    "output": { "asset": "USD", "amount": "10000.00", "vaultId": "vault_usd_settlement" },
    "source": { "type": "BANK_ACCOUNT", "id": "bank_account_ngn_business", "paymentRail": "NIP" },
    "destination": { "type": "BANK_ACCOUNT", "id": "bank_account_usd_supplier", "paymentRail": "ACH" },
    "expiresAt": "2026-09-30T10:00:30+00:00"
  },
  "depositInstructions": {
    "type": "BANK_ACCOUNT",
    "paymentRail": "NIP",
    "bankDetails": {
      "bankName": "Example Settlement Bank",
      "beneficiaryName": "Example settlement beneficiary",
      "accountNumber": "<ACCOUNT_NUMBER_FROM_RESPONSE>"
    },
    "asset": "NGN",
    "memo": "<PAYMENT_REFERENCE_FROM_RESPONSE>"
  }
}

API Basics

Approvals

Accounts

Sub-Orgs

Transactions

Request body

Response

​Request body

​Response

Request body

Response