FX
Execute an FX Quote
Create an FX transaction from a selected quoteId. Returns HTTP 201 with the full Transaction, including deposit instructions when funding is required.
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);
Response example
{
"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>"
}
}
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 FX quote quote_fx_invoice_1042, spending 15,000,000 NGN to pay a 10,000 USD supplier invoice.
Request body
The
quoteId returned by Get Quote.Response
Returns HTTP 201 with a full Transaction. Optional fields depend on the payment route and status.Transaction ID. Use it with Retrieve Transaction to track status.
The executed quote, including its
input, output, source, destination, and expiresAt. See QuoteResponseItem.Where the funds come from, as a TransferPartyData. Which fields are present depends on
type.Where the funds go. Same fields as
source. See TransferPartyData.Aggregate balance movements across the transaction, when present: the input asset debited and the output asset credited. See TransactionOperationBalanceChanges.
Show Properties
Show Properties
One entry per party and asset. See TransactionOperationBalanceChange.
Show Properties
Show Properties
Party whose balance changed. Same fields as
source. See TransferPartyData.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);
Response example
{
"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>"
}
}
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_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);
Response example
{
"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>"
}
}
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;
}