Skip to main content
The transactions group of endpoints allows you to initiate and retrieve transactions from the platform.

​
Initiating a transaction

Transactions in Uphold are RFQ (Request for Quote) based. To create a quote, you call the Create Quote endpoint and present the user with the quote details. Quotes have a unique ID and are valid for a limited time; therefore, you should keep refreshing the quote right before it expires. If the user accepts the quote, you can then execute the transaction by calling the Create Transaction endpoint, passing the quote ID.

​
Anatomy of a quote request

The Create Quote request has three fundamental properties:
  • origin: The origin node of the transaction.
  • destination: The destination node of the transaction.
  • denomination: The denomination of the transaction.
The origin and destination nodes can be of various types:
Account nodes refer to the user’s accounts, which are containers of funds of a given asset, stored in Uphold.
External accounts refer to the user’s external accounts, which allow users to deposit and withdraw funds associated with an external source.
Crypto addresses enable the use of cryptocurrency wallet addresses as transaction nodes within the platform.Crypto transactions can be executed in different modes depending on the destination and environment. Most transactions are processed on-chain directly on the blockchain network. However, when both parties are Uphold users, crypto withdrawals can be processed off-chain within Uphold’s infrastructure, eliminating network fees and reducing processing time.For development and testing purposes, transactions can be simulated without affecting actual blockchain state (user balances will be affected though). The execution mode applied to each transaction is indicated by the execution.mode property in the crypto address node of the API response.
This model allows you to create transactions between different types of nodes in a unified manner, such as between an account and an external account, or between an account and a crypto address. Furthermore, thanks to Uphold’s Anything to Anything technology, you can handle different classes of assets in the origin and destination on a single transaction. For example, you can do a fiat deposit using an external account directly into a BTC account, or you can withdraw from a BTC account directly to an XRP crypto address. The denomination property specifies the amount that will be moved from the origin to the destination. The denomination includes the asset that the amount refers to, which is typically the same as either the origin, the destination, or the user’s national currency, but it can be any asset available on the platform. Moreover, it includes the target property, used to define the side of the transaction that the amount refers to. It can take the value of origin or destination to indicate whether the exact amount should be debited from the origin or credited to the destination respectively, allowing to define who will pay for fees, if any.

​
Transaction lifecycle

Once a transaction is created, it goes through a series of statuses:
  • processing: The transaction is being processed. This is the initial status of a transaction.
  • on-hold: The transaction is on hold and requires further action by Uphold agents. Once the hold is resolved, the transaction will continue processing.
  • completed: The transaction has been successfully completed.
  • failed: The transaction has failed.

​
Transaction types

Transactions do not have a type per se, but they can be classified based on the nodes involved in the transaction. The following are the most common types of transactions:
  • Deposit: A transaction in which the origin is external, such as an external account or a crypto address.
  • Withdrawal: A transaction in which the destination is external, such as an external account or a crypto address.
  • Trade: A transaction in which the origin and destination are accounts of different assets.
  • Transfer: A transaction in which the origin and destination are accounts of the same asset.

​
Relation with capabilities

A transaction can require one or more capabilities to be in a valid state:
  • trades: Required when the underlying origin and destination assets are different.
  • crypto-deposits: Required when the underlying origin is a crypto address.
  • bank-deposits: Required when the underlying origin is an external account of type bank.
  • deposits: Required when the underlying origin is external, such as an external account of type card.
  • receives: Required when the user receives funds from another user.
  • sends: Required when the user sends funds to another user.
  • crypto-withdrawals: Required when the underlying destination network is of type crypto.
  • bank-withdrawals: Required when the underlying destination network is of type bank.
  • card-withdrawals: Required when the underlying destination network is of type card.
⌘I