Introduction

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

Transaction nodes

Every transaction is defined by three fundamental properties:

• origin: Defines the origin node of the transaction.
• destination: Defines the destination node of the transaction.
• denomination: Defines what and how much is being moved.

The origin and destination are each represented by a node. The following node types are supported across the platform:

Account

Account nodes refer to the user’s accounts, which are containers of funds of a given asset, stored in Uphold.

External Account

External accounts refer to the user’s external accounts, which allow users to deposit and withdraw funds associated with an external source.

Crypto Address

Crypto addresses enable the use of crypto 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.

Bank Address

Bank address nodes represent the originating bank account of a push bank deposit, in the cases when adding the originating bank account as an external account is not supported by the platform. They carry the network used for the transfer (e.g. ach).

Initiating a quote-based transaction

Most transactions are RFQ (Request for Quote) based. This applies to:

• Withdrawals: Moving funds out to external accounts or crypto addresses.
• Trades: Converting between different assets.
• Transfers: Moving funds between accounts of the same asset.
• Pull deposits: Deposits where you initiate the transaction (e.g., credit or debit card deposits).

To create a quote, 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. While the user hasn’t confirmed the quote, keep refreshing it before it expires.

If the user accepts the quote, execute the transaction by calling the Create Transaction endpoint, passing the quote ID.

Anatomy of a quote request

The supported node types differ between origin and destination:

• Origin: account external-account
• Destination: account external-account crypto-address

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.

With Uphold’s Anything to Anything system, 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.

Requirements

Some transactions need additional information before they can be executed. When you create a quote, the response includes a requirements array that tells you what extra information is needed — if it’s empty, no extra information is needed.

Check out the Quote Requirements flow for a detailed walkthrough.

Related flows

Check out the following flows for more information on handling quote-based transactions.

Crypto Withdrawal

Withdraw crypto from an account.

Bank Withdrawal

Payout to a bank via quote-based transfers.

Initiating an external transaction

Some deposits (push deposits) are initiated externally when funds arrive from outside sources:

• Crypto deposits: Occur when crypto is sent to a deposit address generated via Set Up Account Deposit Method.
• Bank deposits: Occur when funds are sent to the bank deposit details generated via Set Up Account Deposit Method.

These transactions are created automatically by the platform when incoming funds are detected. You can monitor them via Webhooks or by polling the transaction endpoints.

The supported node types for external transactions are:

• Origin: account external-account crypto-address bank-address
• Destination: account external-account crypto-address

Related flows

Check out the following flows for more information on handling external transactions.

Crypto Deposit

Generate a deposit address and fund it with crypto.

Bank Deposit

Collect bank details (e.g., FPS) and receive push transfers.

Requests for information (RFIs)

When a transaction is placed on hold with reason pending-requests-for-information, that means it requires additional information to proceed. The pending requests for information (RFIs) can be managed using the Requests for Information endpoints.

Check out the Transaction RFIs flow for a detailed walkthrough.

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.