Transaction
14 min
transaction retrieve get api/external/transactions/ use this to paginate through existing transactions with optional filters get /api/external/transactions/?limit={limit}\&page={page}&{filters} request (query params) { "limit" number, "page" number, "params" record\<string, string> } response { "count" number, "next" string | null, "previous" string | null, "results" transaction\[] } help text \ (optional) `limit` page size; defaults to `20` \ (optional) `page` 1 indexed page number; defaults to `1` \ (optional) `params` key value filters accepted by primevault transactions api (e g , `status`, `category`, `vaultid`, `asset`, `externalid`) include only the filters you need example request get /api/external/transactions/?limit=10\&page=2\&status=pending\&vaultid=vault 123 sdk function gettransactions(params? record\<string, string>, page? number, limit? number) promise\<transaction\[]> get api/external/transactions/{transactionid}/ request (path param) { "transactionid" string } response transaction help text \ (required) `transactionid` the unique id returned when the transaction was created or retrieved from a list response (`results\[] id`) example request get /api/external/transactions/txn abc123/ sdk function gettransactionbyid(transactionid string) promise\<transaction> fee estimation post api/external/transactions/estimate fee/ get the estimated fee for a transfer transaction request { "source" transferpartydata, "destination" transferpartydata, "amount" string, "asset" string, "blockchain" string } response estimatedfeeresponse help text \ (required) `source` `transferpartydata` describing the sender (vault/contact/external address plus `id` or `value`) \ (required) `destination` `transferpartydata` describing the recipient \ (required) `amount` decimal string amount you expect to transfer \ (required) `asset` token symbol used for the future transfer \ (required) `blockchain` chain identifier (e g , `ethereum`, `polygon`) that matches both parties example request { "source" { "type" "vault", "id" "vault 123" }, "destination" { "type" "contact", "id" "contact 456" }, "amount" "0 50", "asset" "eth", "blockchain" "ethereum" } sdk function estimatefee(request estimatefeerequest) promise\<estimatedfeeresponse> transfer transaction post api/external/transactions/ json createtransfertransactionrequest request body { "source" { "type" string, "id" string }, "destination" { "type" string, "id" string } | { "type" string, "value" string }, "amount" string, "asset" string, "blockchain" string, "category" "transfer", "gasparams" { "feetier" string } | null, "externalid" string | null, "memo" string | null, "feepayer" { "id" string } | null } response transaction help text "source" transferpartydata object describing the origin (type vault, contact, or external address plus id/value) "destination" transferpartydata object describing where the assets should go "amount" decimal string amount to transfer (e g "0 5" for 0 5 tokens) "asset" asset symbol to send (e g "eth", "usdc") "blockchain" chain identifier that matches the wallet/network (e g "ethereum", "polygon") "category" must be "transfer" to route through the transfer workflow "gasparams" (optional) object with "feetier" to hint low/medium/high fee selection "externalid" (optional) unique string from your system for idempotency/correlation "memo" (optional) free form note retained with the transaction "feepayer" (optional) { "id" string } identifying an alternate vault paying gas js createtransfertransaction(request createtransfertransactionrequest) promise\<transaction> curl curl x post 'https //api primevault com/api/external/transactions/' \\ h 'content type application/json' \\ h 'authorization bearer \<your access token>' \\ d '{ "source" { "type" "vault", "id" "vault 123" }, "destination" { "type" "contact", "id" "contact 456" }, "amount" "0 50", "asset" "eth", "blockchain" "ethereum", "category" "transfer", "gasparams" { "feetier" "medium" }, "externalid" "invoice 1001", "memo" "vendor payout #1001", "feepayer" { "id" "vault 234" } }' response { "id" "txn transfer abc123", "orgid" "org 456", "vaultid" "vault 123", "asset" "eth", "amount" 0 5, "blockchain" "ethereum", "status" "pending", "category" "transfer", "transactiontype" "outgoing", "toaddress" "0xrecipientaddress ", "source" { "type" "vault", "id" "vault 123" }, "destination" { "type" "contact", "id" "contact 456" }, "gasparams" { "expectedgasfeeintoken" "0 002", "gasfeetoken" "eth" }, "externalid" "invoice 1001", "memo" "vendor payout #1001", "createdat" "2025 01 15t10 30 00z", "updatedat" "2025 01 15t10 30 00z" } fee sponser feepayer { "id" string } vault responsible for paying the transaction fee fees are deducted from this vault this represents the actual fee payer, using eip 7702 on evm chains and native fee payer mechanisms on chains such as solana and tron trade transaction create a new trade transaction step 1 get trade quotes fetch the trade quote available for a given asset x chain pair post api/external/transactions/trade quote request (query params/body) { "vaultid" string, "fromasset" string, "fromamount" string, "blockchain" string, "toasset" string, "toblockchain" string, "slippage" string } response gettradequoteresponse help text \ (required) `vaultid` vault providing funds for the swap \ (required) `fromasset` symbol of the asset you are selling \ (required) `fromamount` decimal string of the source amount \ (required) `blockchain` source chain (`fromchain`) for the funds \ (required) `toasset` symbol of the asset you want to receive \ (required) `toblockchain` destination chain (`tochain`) \ (required) `slippage` acceptable slippage percentage as a string (e g , `"1"` for 1%) example request { "vaultid" "vault 789", "fromasset" "usdc", "fromamount" "1000", "blockchain" "ethereum", "toasset" "eth", "toblockchain" "ethereum", "slippage" "1" } example response (truncated) { "traderequestdata" { "fromasset" "usdc", "fromamount" "1000", "blockchain" "ethereum", "toasset" "eth", "toblockchain" "ethereum", "slippage" "1" }, "traderesponsedatalist" \[ { "finaltoamount" "0 52", "finaltoamountusd" "1002 34", "sourcename" "aggregatorx", "feeinusd" "2 00", "autoslippage" "0 5" } ] } sdk function gettradequote(request tradequoterequest) promise\<gettradequoteresponse> step 2 create a trade transaction after selecting a quote from above api, can you pass that quote in the create api post api/external/transactions/ request { "vaultid" string, "traderequestdata" tradequoterequestdata, "traderesponsedata" tradequoteresponsedata, "blockchain" string, "category" enum transactioncategory, "externalid" string, "memo" string } response transaction help text \ (required) `vaultid` the vault executing the trade (source of funds) \ (required) `traderequestdata` the request payload previously used to fetch quotes; include fromasset, fromamount, blockchain, etc \ (required) `traderesponsedata` selected quote entry from `traderesponsedatalist` returned by `gettradequote` \ (required) `blockchain` chain on which the trade executes; should match `traderequestdata blockchain` \ (required) `category` must be `swap` for trade operations \ (optional) `externalid` unique identifier for tracking/idempotency \ (optional) `memo` informational note for audit trails example request { "vaultid" "vault 789", "traderequestdata" { "fromasset" "usdc", "fromamount" "1000", "blockchain" "ethereum", "toasset" "eth", "toblockchain" "ethereum", "slippage" "1" }, "traderesponsedata" { "finaltoamount" "0 52", "finaltoamountusd" "1002 34", "sourcename" "aggregatorx", "feeinusd" "2 00", "autoslippage" "0 5" }, "blockchain" "ethereum", "category" "swap", "externalid" "swap 202", "memo" "rebalance to eth" } sdk function createtradetransaction(request createtradetransactionrequest) promise\<transaction> ramp transaction on ramp use this when ramping from fiat > crypto step 1 get ramp quotes fetch the ramp quote available for a given crypto x fiat pair post /api/external/transactions/quote/ request (body) { "source" { "type" string, "id" string }, "destination" { "type" string, "id" string }, "fromasset" string, "fromamount" string, "fromchain" string, "toamount" string, // only one of the fromamount or toamount should be specified "toasset" string, "tochain" string, "category" "on ramp" | "off ramp", "paymentmethod" string } response rampquoteresponse \[{ "finaltoamount" string, // returned if fromamount is specified in quote request "finalfromamount" string, // returned if toamount is specified in quote request "quoteid" string, "fees" { "amount" string | null, "asset" string | null }, "rate" string | null "sourcename" string }] help text \ (optional) `source` transferpartydata object source of the ramp for on ramp this is the fiat source for off ramp this is the crypto source vault \ (optional) `destination` transferpartydata object destination of the ramp for on ramp this is the crypto destination vault for off ramp this is the fiat destination \ (required) `fromasset` symbol of the asset you are converting from (e g "usd") \ (optional) `fromchain` blockchain of the asset you are converting from \ (required) `fromamount` decimal string of the amount to convert \ (required) `toamount` decimal string of the destination asset only ene of fromamount or toamount should be specified \ (required) `toasset` symbol of the asset you want to receive (e g "usdc") \ (optional) `tochain` destination blockchain (e g "polygon") \ (required) `category` must be "on ramp" or "off ramp" \ (optional) `paymentmethod` payment rail one of "us ach", "us wire", "sepa", "swift", "bank transfer" js getrampquote(request rampquoterequest) promise\<rampquoteresponse> curl curl x post 'https //api primevault com/api/external/transactions/quote/' \\ h 'content type application/json' \\ h 'authorization bearer \<your access token>' \\ d '{ "destination" { "type" "vault", "id" "393f359c 6e66 4490 bf1f 5a4ec44f49d6" }, "fromasset" "usd", "fromamount" "100", "toasset" "usdc", "tochain" "polygon", "category" "on ramp", "paymentmethod" "us ach" }' response { "finaltoamount" "99 93783377213862633", "quoteid" "cde295be 9e25 4760 a21d 83737b8aec60", "fees" { "amount" "0 06216622786137367", "asset" "usd" }, "rate" "1 003" "sourcename" "dummy onramp" } step 2 execute ramp quotes execute the ramp quote for a given crypto x fiat pair post /api/external/transactions/ create an on ramp transaction using a previously fetched ramp quote json createonramptransactionrequest request body { "destination" { "type" string, "id" string }, "quoteid" string, "externalid" string | null, "memo" string | null } response transaction help text "destination" transferpartydata object destination vault for the on ramp crypto delivery (e g { "type" "vault", "id" "vault uuid" }) "quoteid" select the quoteid from rampresponsedata in step 1 "externalid" optional external identifier for client reference "memo" optional short note retained in the transaction record js createonramptransaction(request createonramptransactionrequest) promise\<transaction> curl curl x post 'https //api primevault com/api/external/transactions/' \\ h 'content type application/json' \\ h 'authorization bearer \<your access token>' \\ d '{ "destination" { "type" "vault", "id" "393f359c 6e66 4490 bf1f 5a4ec44f49d6" }, "quoteid" "quote id selected", "externalid" "on ramp 1110eee2e", "memo" "on ramp test" }' response { "id" "txn uuid", "vaultid" "393f359c 6e66 4490 bf1f 5a4ec44f49d6", "orgid" "org uuid", "amount" "100", "asset" "usd", "status" "pending", "category" "on ramp", "subcategory" "string", "transactiontype" "string", "blockchain" "string", "toblockchain" "polygon", "toasset" "usdc", "externalid" "on ramp 1110eee2e", "source" { "type" "string", "id" "string", "bank" { "bankaccountid" "string", "bankname" "string", "accountname" "string", "accountnumber" "string", "routingnumber" "string", "paymentrail" "string", "bankaddress" "string", "swiftcode" "string", "iban" "string" } }, "destination" { "type" "vault", "id" "393f359c 6e66 4490 bf1f 5a4ec44f49d6" }, "ramprequestdata" { "destination" { "type" "vault", "id" "393f359c 6e66 4490 bf1f 5a4ec44f49d6" }, "fromasset" "usd", "fromamount" "100", "toasset" "usdc", "tochain" "polygon", "category" "on ramp", "paymentmethod" "us ach" }, "rampresponsedata" { "finaltoamount" "99 93783377213862633", "quoteid" "cde295be 9e25 4760 a21d 83737b8aec60", "fees" { "amount" "0 06216622786137367", "asset" "usd" }, "rate" "1 003", "sourcename" "dummy onramp" }, "createdat" "2026 03 19t10 30 00z", "updatedat" "2026 03 19t10 30 00z" } off ramp use this when ramping from crypto > fiat step 1 get ramp quotes fetch the ramp quote available for a given crypto x fiat pair post /api/external/transactions/quote/ json request (body) { "source" { "type" string, "id" string }, "destination" { "type" string, "id" string }, "fromasset" string, "fromamount" string, "fromchain" string, "toamount" string, // only one of the fromamount or toamount should be specified "toasset" string, "tochain" string, "category" "on ramp" | "off ramp", "paymentmethod" string } response rampquoteresponse \[{ "finaltoamount" string, // returned if fromamount is specified in quote request "finalfromamount" string, // returned if toamount is specified in quote request "quoteid" string, "fees" { "amount" string | null, "asset" string | null }, "rate" string, "sourcename" string } ] help text \ (optional) `source` transferpartydata object source of the ramp for on ramp this is the fiat source for off ramp this is the crypto source vault \ (optional) `destination` transferpartydata object destination of the ramp for on ramp this is the crypto destination vault for off ramp this is the fiat destination \ (required) `fromasset` symbol of the asset you are converting from (e g "usd") \ (optional) `fromchain` blockchain of the asset you are converting from \ (required) `fromamount` decimal string of the amount to convert \ (required) `toamount` decimal string of the destination asset only ene of fromamount or toamount should be specified \ (required) `toasset` symbol of the asset you want to receive (e g "usdc") \ (optional) `tochain` destination blockchain (e g "polygon") \ (required) `category` must be "on ramp" or "off ramp" \ (optional) `paymentmethod` payment rail one of "us ach", "us wire", "sepa", "swift", "bank transfer" js getrampquote(request rampquoterequest) promise\<rampquoteresponse> curl curl x post 'https //api primevault com/api/external/transactions/quote/' \\ h 'content type application/json' \\ h 'authorization bearer \<your access token>' \\ d '{ "source" { "type" "vault", "id" "393f359c 6e66 4490 bf1f 5a4ec44f49d6" }, "fromasset" "usdt", "fromamount" "100", "toasset" "usd", "fromchain" "ethereum", "category" "off ramp", "paymentmethod" "us ach" }' response { "quotes" \[ { "finaltoamount" "99 50", "quoteid" "abc123de 4567 8901 fghi jklmnopqrst0", "fees" { "amount" "0 50", "asset" "usdt" }, "rate" " 997" "sourcename" "dummy offramp" } ] } step 2 execute ramp quotes execute the ramp quote for a given crypto x fiat pair post /api/external/transactions/ create an off ramp transaction using a previously fetched ramp quote json createofframptransactionrequest request body { "source" { "type" string, "id" string }, "destination" { "type" string, "id" string }, "ramprequestdata" rampquoterequest, "rampresponsedata" rampquoteresponse, "externalid" string | null, "memo" string | null } response transaction help text "source" transferpartydata object source vault for the off ramp crypto withdrawal (e g { "type" "vault", "id" "vault uuid" }) "destination" transferpartydata object destination for the off ramp fiat delivery (e g { "type" "external bank account", "id" "bank account uuid" }) "quoteid" select the quoteid from rampresponsedata in step 1 "externalid" optional external identifier for client reference "memo" optional short note retained in the transaction record js createofframptransaction(request createofframptransactionrequest) promise\<transaction> curl curl x post 'https //api primevault com/api/external/transactions/' \\ h 'content type application/json' \\ h 'authorization bearer \<your access token>' \\ d '{ "source" { "type" "vault", "id" "393f359c 6e66 4490 bf1f 5a4ec44f49d6" }, "destination" { "type" "external bank account", "id" "your approved bank account id" }, "quoteid" "selected quote id", "externalid" "off ramp example 1", "memo" "off ramp test" }' response { "id" "txn uuid", "vaultid" "393f359c 6e66 4490 bf1f 5a4ec44f49d6", "orgid" "org uuid", "amount" "100", "asset" "usdt", "status" "pending", "category" "off ramp", "subcategory" "off ramp", "transactiontype" "outgoing", "blockchain" "ethereum", "externalid" "off ramp example 1", "source" { "type" "vault", "id" "393f359c 6e66 4490 bf1f 5a4ec44f49d6" }, "destination" { "type" "bank account", "id" "your approved bank account id", }, "ramprequestdata" { "source" { "type" "vault", "id" "393f359c 6e66 4490 bf1f 5a4ec44f49d6" }, "fromasset" "usdt", "fromamount" "100", "toasset" "usd", "fromchain" "ethereum", "category" "off ramp", "paymentmethod" "us ach" }, "rampresponsedata" { "finaltoamount" "99 50", "quoteid" "abc123 quote id", "fees" { "amount" "0 50", "asset" "usdt" }, "rate" "0 997" "sourcename" "dummy offramp" }, "memo" "off ramp test", "createdat" "2025 01 01t00 00 00z", "updatedat" "2025 01 01t00 00 00z" } stake transaction post api/external/transactions/ json stakeresourcerequest request body { "source" { "type" string, "id" string }, "asset" string, "blockchain" string, "amount" string, "resourcetype" enum resourcetype, "category" "stake", "externalid" string | null, "memo" string | null } response transaction help text "source" transferpartydata object the vault staking the asset (e g { "type" "vault", "id" "vault uuid" }) "asset" asset symbol to stake (e g "trx") "blockchain" chain identifier for the staking operation (e g "tron") "amount" decimal string amount to stake "resourcetype" (optional) the type of resource to obtain from staking enum values tron energy, tron bandwidth "category" must be "stake" "externalid" optional external identifier for client reference "memo" optional short note retained in the transaction record js stakeresource(request stakeresourcerequest) promise\<transaction> curl curl x post 'https //api primevault com/api/external/transactions/' \\ h 'content type application/json' \\ h 'authorization bearer \<your access token>' \\ d '{ "source" { "type" "vault", "id" "vault 123" }, "asset" "trx", "blockchain" "tron", "amount" "100", "resourcetype" "tron energy", "category" "stake", "externalid" "stake 001", "memo" "stake trx for energy" }' response { "id" "txn stake abc123", "orgid" "org 456", "vaultid" "vault 123", "asset" "trx", "amount" 100, "blockchain" "tron", "status" "pending", "category" "stake", "transactiontype" "outgoing", "source" { "type" "vault", "id" "vault 123" }, "externalid" "stake 001", "memo" "stake trx for energy", "createdat" "2025 01 15t10 30 00z", "updatedat" "2025 01 15t10 30 00z" } delegate transaction post api/external/transactions/ json delegateresourcerequest request body { "source" { "type" string, "id" string }, "destination" { "type" string, "id" string } | { "type" string, "value" string }, "asset" string, "blockchain" string, "amount" string, "resourcetype" enum resourcetype, "category" "delegate resource", "externalid" string | null, "memo" string | null } response transaction help text "source" transferpartydata object the vault delegating resources (e g { "type" "vault", "id" "vault uuid" }) "destination" transferpartydata object the recipient of the delegated resources (e g { "type" "external address", "value" "taddress123" }) "asset" asset symbol used for delegation (e g "trx") "blockchain" chain identifier for the delegation (e g "tron") "amount" decimal string amount to delegate "resourcetype" the type of resource to delegate enum values tron energy, tron bandwidth "category" must be "delegate resource" "externalid" optional external identifier for client reference "memo" optional short note retained in the transaction record js delegateresource(request delegateresourcerequest) promise\<transaction> curl curl x post 'https //api primevault com/api/external/transactions/' \\ h 'content type application/json' \\ h 'authorization bearer \<your access token>' \\ d '{ "source" { "type" "vault", "id" "vault 123" }, "destination" { "type" "external address", "value" "tdestinationaddress123" }, "asset" "trx", "blockchain" "tron", "amount" "50", "resourcetype" "tron energy", "category" "delegate resource", "externalid" "delegate 001", "memo" "delegate energy to partner" }' response { "id" "txn delegate abc123", "orgid" "org 456", "vaultid" "vault 123", "asset" "trx", "amount" 50, "blockchain" "tron", "status" "pending", "category" "delegate resource", "transactiontype" "outgoing", "toaddress" "tdestinationaddress123", "source" { "type" "vault", "id" "vault 123" }, "destination" { "type" "external address", "value" "tdestinationaddress123" }, "externalid" "delegate 001", "memo" "delegate energy to partner", "createdat" "2025 01 15t10 30 00z", "updatedat" "2025 01 15t10 30 00z" }