Introduction

Welcome to the Uphold API — we're glad to have you! Here you can find all the documentation you need to help you create custom and revolutionary new services powered by the Uphold Platform. Together, with your ingenuity, we can serve the needs of individuals and organizations across the globe and change the financial services ecosystem forever.

API code samples

To help you get started, we have prepared a set of fully functional code samples. Each of these is a self-contained mini-project, with step-by-step documentation, built specifically to be downloaded and run locally. You can inspect the demo code of these samples to get acquainted with how to use the Uphold API to perform various actions, such as making authenticated requests and creating transactions. By default, all of the samples use our Sandbox environment, which provides a safe playground to experiment with the API without using real funds.

You may also use our JavaScript SDK, a JavaScript API client library that provides a higher-level and richer experience in integrating with our API.

API Changes

You can be notified of the latest changes by watching our official documentation repository on GitHub.

Applications

Registering an application

Developers will need to register their application before getting started. A registered application will be assigned a unique Client Id and Client Secret.

Considerations

For security reasons, your application must be secured with a valid SSL certificate issued by a known Certificate Authority.
Likewise, the provided Redirect URL when registering the application must be a valid static subresource. Notice that this property cannot be dynamically reconfigured during authorization requests for security reasons.
The Redirect URL can also be a valid URI with a non-http/https protocol which is useful for mobile and desktop applications, for example: my-app://uphold/connect.
Users can revoke access to your application at any time. Your application must be prepared for this and, if necessary, should request authorization from the user again.
Likewise, when users change their password, all authorization tokens are expired and the user enters a cool-down period where outbound transactions are not allowed, for security reasons. Your application must be prepared for this.
Your application may be suspended in an automated fashion in accordance with our Terms of Service.
Standard rate limits apply to all issued access tokens.

Permissions

When requesting authorization from a user the application must specify the level of access needed. These scopes are displayed to the user on the authorization form and currently the user cannot opt-out of individual scopes.

The API supports the following scopes:

Scope	Description
accounts:read	Can view all accounts and their information.
cards:read	Can view all cards and their information.
cards:write	Can create and update any card.
phones:read	Can view all phone numbers and their information.
phones:write	Can add new phone numbers.
transactions:deposit	Can create a deposit transaction.
transactions:read	Can view any transaction.
transactions:transfer:application	Can create a transaction between the user and the application.
transactions:transfer:others	Can create a transaction between different users.
transactions:transfer:self	Can create a transaction between a user's cards.
transactions:withdraw	Can create a withdrawal transaction.
user:read	Can view the user and their information.

Deprecated scopes

The following scopes are deprecated and will be removed in a future version of the API:

Scope	Description
transactions:write	Can create a transaction from any origin to any destination (another card or an external address), cancel and resend transactions. This scope is now deprecated in favor of the more fine-grained write scopes above (deposit, transfer and withdraw).

Resources

We prefer that you use these image resources when connecting your applications to Uphold.

Connect
small (129x40), large (258x80), vector (SVG)

Connect with Uphold
small (206x40), large (412x80), vector (SVG)

Connect
small (129x40), large (258x80), vector (SVG)

Connect with Uphold
small (206x40), large (412x80), vector (SVG)

Authentication

Uphold is an OAuth 2.0-compliant service.

Partners looking to integrate with our API must register an application. Applications that implement a user-facing web interface, to provide custom functionality for multiple Uphold users, should use the Web Application Flow. Applications that implement a backend interface for a corporate partner (and therefore represent an Uphold user themselves) should use the Client Credentials Flow.

Web Application Flow

Ideal for web applications that wish to retrieve information about a user's Uphold account or take actions on their behalf.

Step 1 - Authorization

The authenticating web application should redirect users to the following URL:

https://wallet.uphold.com/authorize/<client_id>

Or for Sandbox applications:

https://wallet-sandbox.uphold.com/authorize/<client_id>

Example of an authorization request URL:

https://wallet.uphold.com/authorize/<client_id>?state=<state_string>&scope=accounts:read%20cards:read

Supported query parameters:

Parameter	Required	Description
intention	no	By default, unauthenticated users will be redirected to the `login` page. This behavior can be changed by sending `signup` as the `intention` value.
scope	yes	Permissions to request from the user. Multiple scopes should be separated by spaces.
state	yes	An unguessable, cryptographically secure random string used to protect against cross-site request forgery attacks.

Step 2 - Requesting a Token

Exchanging the code for a token:

curl https://api.uphold.com/oauth2/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u <clientId>:<clientSecret> \
  -d 'code=<code>&grant_type=authorization_code'

If your request for a token checks out, then our API will return the following:

{
  "access_token": "41ee8b1fa14042e031fe304bb4793b54e6576d19b306dc205136172b80d59d20",
  "expires_in": null
}

If the user accepts your request, Uphold will redirect the user back to your site with a temporary code and the previously provided state, as is.

This temporary code is valid for a duration of 5 minutes and can only be used once.

Your application is responsible for ensuring that the state matches the value previously provided, thus preventing a malicious third-party from forging this request.

You may then exchange this code for an access token using the following endpoint:

POST https://api.uphold.com/oauth2/token

Or for Sandbox applications:

https://api-sandbox.uphold.com/oauth2/token

Supported parameters:

Parameter	Required	Description
client_id	yes	The application's clientId. Please use HTTP Basic Authentication when possible.
client_secret	yes	The application's clientSecret. Please use HTTP Basic Authentication when possible.
code	yes	The code acquired in step 1.
grant_type	yes	Must be set to 'authorization_code'.

Step 3 - Using the Access Token

Request using the 'Authorization' header:

curl https://api.uphold.com/v0/me/cards \
  -H "Authorization: Bearer <token>"

Once you have obtained an access token you may call any protected API method on behalf of the user using the "Authorization" HTTP header in the format:

Authorization: Bearer <token>

Client Credentials Flow

Ideal for backend integrations that do not require access to other Uphold user accounts.

For business usage only you may choose to use client credentials authentication. This requires manual approval from Uphold.

Creating a Token

To create a client credentials token, execute the following command (make sure the application is set to use client credentials and not authorization code):

curl https://api.uphold.com/oauth2/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u <clientId>:<clientSecret> \
  -d 'grant_type=client_credentials'

To create a client credentials token you may use the following endpoint:

POST https://api.uphold.com/oauth2/token

Supported parameters:

Parameter	Required	Description
client_id	yes	The application's clientId. Please use HTTP Basic Authentication when possible.
client_secret	yes	The application's clientSecret. Please use HTTP Basic Authentication when possible.
grant_type	yes	Must be set to 'client_credentials'.

Using the Token

Request using the 'Authorization header':

curl https://api.uphold.com/v0/me/cards \
  -H "Authorization: Bearer <token>"

Once you have obtained a client credentials token you may call any protected API method on behalf of the user account owner of the application using the "Authorization" HTTP header in the format:

Authorization: Bearer <token>

Personal Access Tokens (PAT)

Ideal for scripts, automated tools and command-line programs which remain under your control.

For personal usage only you may choose to use a PAT. This token establishes who you are, provides full access to your user account and bypasses Two Factor Authentication, if enabled. For this reason it should be treated just like your email/password combination, i.e. remain secret and never shared with third parties. PATs can be issued and revoked individually.

Listing PATs

To list active Personal Access Tokens, execute the following command:

curl https://api.uphold.com/v0/me/tokens \
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

[
  {
    "description": "token 1",
    "id": "a97bb994-6e24-4a89-b653-e0a6d0bcf634"
  },
  {
    "description": "token 2",
    "id": "b97bb994-6e24-4a89-b653-e0a6d0bcf635"
  }
]

To list Personal Access Tokens you may use the following endpoint:

GET https://api.uphold.com/v0/me/tokens

Creating a PAT

To create a Personal Access Token, execute the following command:

curl https://api.uphold.com/v0/me/tokens \
  -X POST \
  -H "Content-Type: application/json" \
  -H "OTP-Token: <OTP-Token>" \
  -u <email>:<password> \
  -d '{ "description": "My command line script" }'

The above command returns the following JSON:

{
  "accessToken":"c386ae9c4557c1c661b15911071b06d9e6c3fc9a",
  "description":"My command line script",
  "id":"a97bb994-6e24-4a89-b653-e0a6d0bcf634"
}

To create a Personal Access Token you may use the following endpoint:

POST https://api.uphold.com/v0/me/tokens

Supported parameters:

Parameter	Required	Description
description	yes	A human-readable description of this PAT.

Requires the OTP-Token header with a valid TOTP token.

Revoking a PAT

To revoke a Personal Access Token, execute the following command:

curl https://api.uphold.com/v0/me/tokens/:token \
  -X DELETE \
  -H "Authorization: Bearer <token>"

To revoke a Personal Access Token you may use the following endpoint:

DELETE https://api.uphold.com/v0/me/tokens/:token

Supported parameters:

Parameter	Required	Description
token	yes	The PAT you wish to revoke.

Using a PAT

Example of using a personal access token to make requests to our API:

curl https://api.uphold.com/v0/me \
  -H "Authorization: Bearer <token>"

A PAT may be used for authenticating a request via the OAuth scheme.

The <token> should be set as the accessToken received during creation.

Basic Authentication

Simple request using email and password:

curl https://api.uphold.com/v0/me \
  -H 'OTP-Token: <OTP-Token>' \
  -u <email>:<password>

You can use Basic Authentication by providing your email and password combination.

If OTP (One-Time Password, also known as Two-Factor Authentication) is required, then you will get a 401 HTTP error, along with the HTTP header OTP-Token: Required. In which case, execute the command above again, this time passing your OTP verification code header, like so: OTP-Token: <OTP-Token>.

One-Time Password

Uphold provides a TOTP (Time-Based One-Time Password) mechanism to secure user accounts. Adopting and adhering to this mechanism is recommended for safety reasons. The following section documents how the Authentication Methods API works to provide support for this security mechanism.

List Authentication Methods

curl https://api.uphold.com/v0/me/authentication_methods \
  -u <email>:<password>

The above command returns the following JSON:

[{
  "default": false,
  "id": "3f8f8264-2f5e-4b2b-8333-473715ab039a",
  "label": "Authenticator TOTP",
  "type": "totp",
  "verified": true,
  "verifiedAt": "2019-02-11T14:31:48.485Z"
},
{
  "default": true,
  "id": "be95ed5f-d048-4348-9572-411df23bedc9",
  "label": "+XXXXXXXXXX57",
  "type": "authy",
  "verified": true,
  "verifiedAt": "2019-01-11T14:20:04.055Z"
}]

Retrieves a list of authentication methods for the current user.

Request

GET https://api.uphold.com/v0/me/authentication_methods

Response

Returns an array of the current user's authentication methods.

Add Authentication Method

curl https://api.uphold.com/v0/me/authentication_methods/totp \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H 'OTP-Token: <OTP-Token>'

The above command returns the following JSON:

{
  "default": false,
  "id": "3f8f8264-2f5e-4b2b-8333-473715ab039a",
  "label": "Authenticator TOTP",
  "type": "totp",
  "url": "otpauth://totp/Uphold:[email protected]?algorithm=SHA1&digits=6&issuer=Uphold&period=30&secret=QRV62S3O6LXDB7FRKR4LMF3VGR6MZT7S",
  "verified": false,
  "verifiedAt": null
}

Request

POST https://api.uphold.com/v0/me/authentication_methods/totp

Requires the OTP-Token header with a valid TOTP token.

Response

Returns a fully formed Authentication Method representing the authentication method created.

Verify Authentication Method

curl https://api.uphold.com/v0/me/authentication_methods/3f8f8264-2f5e-4b2b-8333-473715ab039a/verify \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "token": "<OTP-Token>" }'

The above command returns the following JSON:

{
  "default": false,
  "id": "3f8f8264-2f5e-4b2b-8333-473715ab039a",
  "label": "Authenticator TOTP",
  "type": "totp",
  "verified": true,
  "verifiedAt": "2019-02-11T14:31:48.485Z"
}

Request

POST https://api.uphold.com/v0/me/authentication_methods/:id/verify

Response

Returns an Authentication Method object representing the verified authentication method.

Remove Authentication Method

curl https://api.uphold.com/v0/me/authentication_methods/3f8f8264-2f5e-4b2b-8333-473715ab039a \
  -X DELETE \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "OTP-Token: <OTP-Token>"

The above command does not return a JSON response.

Request

DELETE https://api.uphold.com/v0/me/authentication_methods/3f8f8264-2f5e-4b2b-8333-473715ab039a

Requires the OTP-Token header to be sent with a valid TOTP token.

Response

Returns an HTTP status code of 204 and no JSON body, in case of success.

Webhooks

For business usage only you may choose to use webhooks to get updates in real time instead of having to poll the API. This requires manual approval from Uphold.

A webhooks integration requires the following details:

Subscription URL: the URL for Uphold to send webhook requests to;
Secret: the secret for Uphold to use to sign all requests and prove they have not been tampered with (not the same as the client secret that is used for Uphold's API).

Each webhook uses the following format:

Parameter	Description
createdAt	Timestamp of the notification, can be used to verify message ordering.
id	Unique identifier of the notification, can be used to ignore duplicate notifications.
payload	JSON with the actual model data being sent by the webhook.
retries	Number of retries of the notification, in case of failure of previous requests (e.g. the request getting an HTTP response not in the 2xx range).
type	Type of the notification (e.g. `card:updated`).
userId	Unique identifier of the Uphold user that owns the resource.

In addition, the request also includes a signature header, that can be used to verify that the request body has not been tampered with. That header is generated by signing the request body with the previously provided secret, using the SHA512 algorithm.

Example of signature header:

sha512=040518ad86dd4bea08ba6d23240f53a9f35175bcb3c548e83f33acc792aabcafe29954f92b0e1d6ede9192c851b3ba0768f760f516e168c7b318a17d2714bf52

Card updated

If you want to be notified whenever a given card's balance changes, you can use the "Card Updated" scope. This is useful when you want to perform actions regarding the user's total balance or the balance of a specific card, so that you can act accordingly.

The following is a card:updated webhook payload example:

{
  "createdAt": "2018-05-03T12:25:21.809Z",
  "id": "c4db98e4-c9e1-46dc-a927-17a26fb9772c",
  "payload": {
    "context": {
      "transaction": {
        "id": "fd2907af-5bcd-488e-9310-42993d0e375e"
      }
    },
    "id": "c4a77706-7b3a-4b8b-968b-4190038d37e8"
  },
  "retries": 0,
  "type": "card:updated",
  "userId": "e5b23ad5-6c1e-44d0-a49d-a080135fc083"
}

This webhook returns the following payload:

Parameter	Description
context	A JSON object with additional context.
id	The id of the updated card.

The additional context includes the following details:

Parameter	Description
transaction	A JSON object with the id of the transaction that triggered the update.

It returns the card details and context whenever a card has changed its available or balance, i.e. whenever it sends or receives a transaction. The context includes the id of that transaction.

OAuth authorization revoked

This webhook is triggered when a user that had previously authorized your app decides to remove said authorization. When this happens, you'll receive a request informing you of which user has removed the authorization. To subscribe to these updates, you'll need to configure a webhook with the "OAuth Authorization Revoked" scope.

The following is a oauth-authorization:revoked webhook payload example:

{
  "createdAt": "2018-05-03T12:25:21.809Z",
  "id": "c4db98e4-c9e1-46dc-a927-17a26fb9772c",
  "payload": {
    "id": "758d3c93-5f00-46dd-a1b3-facdc215e09b"
  },
  "retries": 0,
  "type": "oauth-authorization:revoked",
  "userId": "e5b23ad5-6c1e-44d0-a49d-a080135fc083"
}

This webhook returns the following payload:

Parameter	Description
id	The id of the authorization.

It returns the id of the authorization that was revoked.

Transaction status

When you create a transaction, the first set of validations is run and you'll get an error if the transaction request is not valid. Otherwise, the request is completed successfully and the response body will contain a status property with value processing. In the meantime, we perform another set of validations that can lead to a transaction's status becoming failed or completed. This asynchronous behavior can be handled by subscribing to a webhook with the "Transaction Status Updated" scope, which will allow you to receive updates whenever a transaction created by your application changes its status.

The following is a transaction:status:updated webhook payload example:

{
  "createdAt": "2018-05-03T12:25:21.809Z",
  "id": "c4db98e4-c9e1-46dc-a927-17a26fb9772c",
  "payload": {
    "id": "c4a77706-7b3a-4b8b-968b-4190038d37e8",
    "status":  "completed"
  },
  "retries": 0,
  "type": "transaction:status:updated",
  "userId": "e5b23ad5-6c1e-44d0-a49d-a080135fc083"
}

This webhook returns the following payload:

Parameter	Description
id	The id of the transaction.
status	A string with the transaction status that triggered the hook.
	Possible values are: `cancelled`, `completed`, `failed` and `waiting`.

It returns the id of the created transaction, along with its current status.

Currencies

Uphold supports multiple financial assets, including traditional currencies, cryptocurrencies, stablecoins, precious metals, U.S. equities, and more.

In Uphold's API, various endpoints include currencies in their input or output. We represent all such currencies by an abbreviation code of variable length, typically containing uppercase letters (for example, a currency's ISO 4217 code, an equity's ticker symbol, or other similar well-known representation).

List Supported Assets

Example of unauthenticated request to list all supported assets:

curl https://api.uphold.com/v0/assets

The above command returns JSON in the following format:

[
  {
    "code": "BTC",
    "formatting": {
      "decimal": ".",
      "format": "__symbol__ __value__ __code__",
      "grouping": ",",
      "precision": 8
    },
    "name": "Bitcoin",
    "status": "open",
    "symbol": "₿",
    "type": "cryptocurrency"
  },
  {
    "code": "USD",
    "formatting": {
      "decimal": ".",
      "format": "__symbol__ __value__ __code__",
      "grouping": ",",
      "precision": 2
    },
    "name": "US Dollar",
    "status": "open",
    "symbol": "$",
    "type": "fiat"
  },
  {
    "code": "XPT",
    "formatting": {
      "decimal": ".",
      "format": "__code__ __value__ __symbol__",
      "grouping": ",",
      "precision": 8
    },
    "name": "Platinum",
    "status": "open",
    "symbol": "oz",
    "type": "commodity"
  },
  {
    "code": "AAPL",
    "formatting": {
      "decimal": ".",
      "format": "__value__ __code__",
      "grouping": ",",
      "precision": 6
    },
    "name": "Apple",
    "status": "extended",
    "type": "equity"
  }
]

Example of authenticated request to list only the assets available to the current user:

curl https://api.uphold.com/v0/assets \
  -H "Authorization: Bearer <token>"

Example of filtering the list to show only assets of specific types:

curl https://api.uphold.com/v0/assets?q=type:cryptocurrency,fiat,equity

Get the list of supported currencies and other financial assets, with details as described by the table below:

Property	Description
code	Uppercase abbreviation of the asset, e.g. "BTC", USD", "C", or "BRK.B".
formatting	Specification for user-facing display, including number formatting and placement of the code and symbol.
name	Full name of the asset, e.g. "Euro", "Basic Attention Token", or "0x".
status	Current trading status. See below for more details.
symbol	A short and well-known representation of the asset, if one exists — e.g. "$", "₿", or "Kč".
type	Type of asset. Possible values are `commodity`, `cryptocurrency`, `equity`, `fiat`, `stablecoin` and `utility_token`.

If the request is unauthenticated, the full list of assets supported by Uphold is returned. Authenticated requests, on the other hand, will filter the output, returning only the assets available for the current user, which can depend on factors such as their country and state of residency.

The list of assets returned can also be filtered by type using a query string parameter, as shown in the example to the side.

Please note that this endpoint is paginated, due to the large number of supported assets (hundreds), so multiple requests may be required to get the complete list.

Asset status

The status field of an asset indicates whether it can be transacted at the moment. The possible values are:

closed — the asset is temporarily disabled for trading; used for equities during periods outside the U.S. stock market's trading hours (typically from 9:30am to 4:00pm ET on weekdays).
extended — used for equities that we make available for trading outside the U.S. stock market's trading hours. Transactions made with assets in this status will settle instantly for the user, but will have a higher spread, as Uphold takes financial risk to provide this service.
halted — trading has been temporarily disabled due to extraordinary circumstances. This can be the case e.g. if a provider is down, or when a cryptocurrency is undergoing a fork.
open — the asset is in regular operation and transactions can be made with it. Most assets remain in this status save for exceptional circumstances, where they can become halted. Equities, on the other hand, will regularly transition between open and either closed or extended, depending on their availability for 24/7 operation.

Tickers

At any time, you can query the rates we utilize when exchanging one form of value for another. These are expressed in currency pairs.

Get Tickers for Currency

curl https://api.uphold.com/v0/ticker/USD

The above command returns JSON in the following format:

[{
  "ask": "0.27226",
  "bid": "0.27226",
  "currency": "USD",
  "pair": "AEDUSD"
},
{
  "ask": "0.02675",
  "bid": "0.02675",
  "currency": "USD",
  "pair": "ARSUSD"
},
{
  "ask": "0.72624",
  "bid": "0.72624",
  "currency": "USD",
  "pair": "AUDUSD"
},
{
  "ask": "0.15813",
  "bid": "0.15733",
  "currency": "USD",
  "pair": "BATUSD"
},
{
  "ask": "437.67",
  "bid": "436.02",
  "currency": "USD",
  "pair": "BCHUSD"
},
{
  "ask": "0.24239",
  "bid": "0.24239",
  "currency": "USD",
  "pair": "BRLUSD"
},
{
  "ask": "6420.05",
  "bid": "6419",
  "currency": "USD",
  "pair": "BTCUSD"
},
{
  "ask": "21.83459",
  "bid": "21.61919",
  "currency": "USD",
  "pair": "BTGUSD"
},
{
  "ask": "0.77245",
  "bid": "0.77245",
  "currency": "USD",
  "pair": "CADUSD"
},
{
  "ask": "1.03568",
  "bid": "1.03568",
  "currency": "USD",
  "pair": "CHFUSD"
},
{
  "ask": "0.14552",
  "bid": "0.14552",
  "currency": "USD",
  "pair": "CNYUSD"
},
{
  "ask": "184.17319",
  "bid": "183.07604",
  "currency": "USD",
  "pair": "DASHUSD"
},
{
  "ask": "0.15799",
  "bid": "0.15799",
  "currency": "USD",
  "pair": "DKKUSD"
},
{
  "ask": "210.5",
  "bid": "210.17",
  "currency": "USD",
  "pair": "ETHUSD"
},
{
  "ask": "1.17848",
  "bid": "1.17848",
  "currency": "USD",
  "pair": "EURUSD"
},
{
  "ask": "1.31527",
  "bid": "1.31527",
  "currency": "USD",
  "pair": "GBPUSD"
},
{
  "ask": "0.12805",
  "bid": "0.12805",
  "currency": "USD",
  "pair": "HKDUSD"
},
{
  "ask": "0.27898",
  "bid": "0.27898",
  "currency": "USD",
  "pair": "ILSUSD"
},
{
  "ask": "0.01377",
  "bid": "0.01377",
  "currency": "USD",
  "pair": "INRUSD"
},
{
  "ask": "0.00886",
  "bid": "0.00886",
  "currency": "USD",
  "pair": "JPYUSD"
},
{
  "ask": "0.0099",
  "bid": "0.0099",
  "currency": "USD",
  "pair": "KESUSD"
},
{
  "ask": "0.02671",
  "bid": "0.02664",
  "currency": "USD",
  "pair": "LBAUSD"
},
{
  "ask": "55.51",
  "bid": "55.39",
  "currency": "USD",
  "pair": "LTCUSD"
},
{
  "ask": "0.05264",
  "bid": "0.05264",
  "currency": "USD",
  "pair": "MXNUSD"
},
{
  "ask": "0.12313",
  "bid": "0.12313",
  "currency": "USD",
  "pair": "NOKUSD"
},
{
  "ask": "0.6658",
  "bid": "0.6658",
  "currency": "USD",
  "pair": "NZDUSD"
},
{
  "ask": "0.01841",
  "bid": "0.01841",
  "currency": "USD",
  "pair": "PHPUSD"
},
{
  "ask": "0.27465",
  "bid": "0.27465",
  "currency": "USD",
  "pair": "PLNUSD"
},
{
  "ask": "0.11368",
  "bid": "0.11368",
  "currency": "USD",
  "pair": "SEKUSD"
},
{
  "ask": "0.73244",
  "bid": "0.73244",
  "currency": "USD",
  "pair": "SGDUSD"
},
{
  "ask": "3.67302",
  "bid": "3.67302",
  "currency": "AED",
  "pair": "USDAED"
},
{
  "ask": "37.384",
  "bid": "37.384",
  "currency": "ARS",
  "pair": "USDARS"
},
{
  "ask": "1.37695",
  "bid": "1.37695",
  "currency": "AUD",
  "pair": "USDAUD"
},
{
  "ask": "6.356066865823428462",
  "bid": "6.323910706380825903",
  "currency": "BAT",
  "pair": "USDBAT"
},
{
  "ask": "0.00229347",
  "bid": "0.00228483",
  "currency": "BCH",
  "pair": "USDBCH"
},
{
  "ask": "4.1255",
  "bid": "4.1255",
  "currency": "BRL",
  "pair": "USDBRL"
},
{
  "ask": "0.00015579",
  "bid": "0.00015576",
  "currency": "BTC",
  "pair": "USDBTC"
},
{
  "ask": "0.0462552",
  "bid": "0.04579889",
  "currency": "BTG",
  "pair": "USDBTG"
},
{
  "ask": "1.29458",
  "bid": "1.29458",
  "currency": "CAD",
  "pair": "USDCAD"
},
{
  "ask": "0.96555",
  "bid": "0.96555",
  "currency": "CHF",
  "pair": "USDCHF"
},
{
  "ask": "6.8717",
  "bid": "6.8717",
  "currency": "CNY",
  "pair": "USDCNY"
},
{
  "ask": "0.00546221",
  "bid": "0.00542967",
  "currency": "DASH",
  "pair": "USDDASH"
},
{
  "ask": "6.32967",
  "bid": "6.32967",
  "currency": "DKK",
  "pair": "USDDKK"
},
{
  "ask": "0.004758053004710472",
  "bid": "0.004750593824228029",
  "currency": "ETH",
  "pair": "USDETH"
},
{
  "ask": "0.84855",
  "bid": "0.84855",
  "currency": "EUR",
  "pair": "USDEUR"
},
{
  "ask": "0.7603",
  "bid": "0.7603",
  "currency": "GBP",
  "pair": "USDGBP"
},
{
  "ask": "7.80938",
  "bid": "7.80938",
  "currency": "HKD",
  "pair": "USDHKD"
},
{
  "ask": "3.58455",
  "bid": "3.58455",
  "currency": "ILS",
  "pair": "USDILS"
},
{
  "ask": "72.62198",
  "bid": "72.62198",
  "currency": "INR",
  "pair": "USDINR"
},
{
  "ask": "112.81103",
  "bid": "112.81103",
  "currency": "JPY",
  "pair": "USDJPY"
},
{
  "ask": "101.00997",
  "bid": "101.00997",
  "currency": "KES",
  "pair": "USDKES"
},
{
  "ask": "37.537537537537537538",
  "bid": "37.439161362785473605",
  "currency": "LBA",
  "pair": "USDLBA"
},
{
  "ask": "0.0180538",
  "bid": "0.01801477",
  "currency": "LTC",
  "pair": "USDLTC"
},
{
  "ask": "18.9965",
  "bid": "18.9965",
  "currency": "MXN",
  "pair": "USDMXN"
},
{
  "ask": "8.1213",
  "bid": "8.1213",
  "currency": "NOK",
  "pair": "USDNOK"
},
{
  "ask": "1.50195",
  "bid": "1.50195",
  "currency": "NZD",
  "pair": "USDNZD"
},
{
  "ask": "54.309",
  "bid": "54.309",
  "currency": "PHP",
  "pair": "USDPHP"
},
{
  "ask": "3.64098",
  "bid": "3.64098",
  "currency": "PLN",
  "pair": "USDPLN"
},
{
  "ask": "8.79693",
  "bid": "8.79693",
  "currency": "SEK",
  "pair": "USDSEK"
},
{
  "ask": "1.3653",
  "bid": "1.3653",
  "currency": "SGD",
  "pair": "USDSGD"
},
{
  "ask": "7.20046083",
  "bid": "7.18752246",
  "currency": "VOX",
  "pair": "USDVOX"
},
{
  "ask": "0.06919122",
  "bid": "0.06659874",
  "currency": "XAG",
  "pair": "USDXAG"
},
{
  "ask": "0.0008392",
  "bid": "0.00082561",
  "currency": "XAU",
  "pair": "USDXAU"
},
{
  "ask": "0.00094715",
  "bid": "0.00091395",
  "currency": "XPD",
  "pair": "USDXPD"
},
{
  "ask": "0.00120104",
  "bid": "0.00115312",
  "currency": "XPT",
  "pair": "USDXPT"
},
{
  "ask": "2.176231",
  "bid": "2.175474",
  "currency": "XRP",
  "pair": "USDXRP"
},
{
  "ask": "0.13913",
  "bid": "0.13888",
  "currency": "USD",
  "pair": "VOXUSD"
},
{
  "ask": "15.0153",
  "bid": "14.4527",
  "currency": "USD",
  "pair": "XAGUSD"
},
{
  "ask": "1211.224",
  "bid": "1191.608",
  "currency": "USD",
  "pair": "XAUUSD"
},
{
  "ask": "1094.1465",
  "bid": "1055.7955",
  "currency": "USD",
  "pair": "XPDUSD"
},
{
  "ask": "867.2155",
  "bid": "832.614",
  "currency": "USD",
  "pair": "XPTUSD"
},
{
  "ask": "0.45967",
  "bid": "0.45951",
  "currency": "USD",
  "pair": "XRPUSD"
}]

Lists all exchange rates relative to a given currency.

Request

GET https://api.uphold.com/v0/ticker/:currency

Response

Returns an associative array containing the current rates Uphold has on record for the currency specified. If no currency is specified on the endpoint, USD currency pair will be returned by default.

Get Tickers for Currency Pair

curl https://api.uphold.com/v0/ticker/USD-EUR

The above command returns JSON in the following format:

{
  "ask":"0.87742",
  "bid":"0.87742",
  "currency":"EUR"
}

curl https://api.uphold.com/v0/ticker/EUR-USD

The above command returns JSON in the following format:

{
  "ask":"1.13985",
  "bid":"1.13985",
  "currency":"USD"
}

Retrieves the exchange rate of a currency relative to any other currency.

As is shown in the example, the endpoint will provide the exchange rate from the first currency to the second currency.

Request

GET https://api.uphold.com/v0/ticker/:pair

Response

Returns an object containing the current rate Uphold has on record for the specified currency pair.

Entities

Account Object

An example account encoded in JSON looks like this:

{
  "billing": {
    "name": "Abigail Davis"
  },
  "brand": "visa",
  "currency": "USD",
  "id": "0874745c-f0bf-4973-a3d9-9832aeaae087",
  "label": "Savings Account",
  "status": "ok",
  "type": "card"
}

Property	Description
billing	The relevant billing details associated with the account.
brand	The brand of the `card` account.
currency	The currency in which the account is denominated.
id	A unique ID associated with the account.
label	The display name of the account as chosen by the user.
status	The current status of the account. Possible values are `ok` and `failed`.
type	The type of the account. Possible values are `card` and `sepa`.

Authentication Method Object

An example authentication method encoded in JSON looks like this:

{
  "default": false,
  "id": "3f8f8264-2f5e-4b2b-8333-473715ab039a",
  "label": "Authenticator TOTP",
  "type": "totp",
  "verified": true,
  "verifiedAt": "2019-02-11T14:31:48.485Z"
}

Property	Description
default	A boolean signalling whether or not the method is the default.
id	A unique ID associated with the account.
label	The display name of the authentication method.
type	The type of authentication method. Possible values are `authy` and `totp`.
verified	A boolean signalling whether or not the authentication method has been verified.
verifiedAt	The date and time of verification of the authentication method.

Card Object

An example card encoded in JSON looks like this:

{
  "address": {
    "bitcoin": "ms22VBPSahNTxHZNkYo2d4Rmw1Tgfx6ojr"
  },
  "available": "146.38",
  "balance": "146.38",
  "currency": "EUR",
  "id": "bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3",
  "label": "EUR card",
  "lastTransactionAt": "2018-08-01T09:53:51.258Z",
  "normalized": [{
    "available": "170.96",
    "balance": "170.96",
    "currency": "USD"
  }],
  "settings": {
    "position": 2,
    "protected": false,
    "starred": true
  }
}

Property	Description
address	A key/value pair representing the primary address for the card.
available	The balance available for withdrawal/usage.
balance	The total balance of the card, including all pending transactions.
currency	The currency by which the card is denominated.
id	A unique ID associated with the card.
label	The display name of the card as chosen by the user.
lastTransactionAt	A timestamp of the last time a transaction on this card was conducted.
normalized	Contains the normalized `available` and `balance` values in the currency set by the user in the settings.
settings	This property contains the following keys:
	`starred`: Indicates whether the card is `starred` or not.
	`DEPRECATED` `position`: The card's current position.

Currency Pair Object

An example currency pair encoded in JSON looks like this:

{
  "ask": "6420.05",
  "bid": "6419",
  "currency": "USD",
  "pair": "BTCUSD"
}

A currency pair is the combination of two currencies, encoded as two currency codes concatenated together to represent the current status of converting the first currency into the second. For example, the currency pair "BTCUSD" represents moving from bitcoin to US dollars.

Each currency pair has four properties:

Property	Description
ask	The current ask price, or the price we quote when selling the asset.
bid	The current bid price, or the price we quote when buying the asset.
currency	The currency that is used in the `ask` and `bid` prices.
pair	The currency pair AB represents moving from A to B.

Phone Object

An example phone encoded in JSON looks like this:

{
  "e164Masked": "+XXXXXXXXX04",
  "id": "1d78aeb5-43ac-4ee8-8d28-1291b5d8355c",
  "internationalMasked": "+X XXX-XXX-XX04",
  "nationalMasked": "(XXX) XXX-XX04",
  "primary": true,
  "verified": true
}

Property	Description
e164Masked	The masked representation of the phone number in the E.164 format.
id	A unique ID in the Uphold platform identifying the phone.
internationalMasked	The masked representation of the phone number in international format.
nationalMasked	The masked representation of the phone number in national format.
primary	A boolean indicating if this phone number is the user's primary phone number.
verified	A boolean indicating if this phone number has been verified.

For more information about the specifics of the "international" and "national" phone number formats, refer to the implementation of the google-libphonenumber package.

Transaction Object

An example transaction encoded in JSON looks like this:

{
  "application": null,
  "createdAt": "2018-08-01T09:53:47.020Z",
  "denomination": {
    "amount": "5.00",
    "currency": "GBP",
    "pair": "GBPUSD",
    "rate": "1.31"
  },
  "destination": {
    "CardId": "bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3",
    "amount": "5.57",
    "base": "5.61",
    "commission": "0.04",
    "currency": "EUR",
    "description": "Angel Rath",
    "fee": "0.00",
    "isMember": true,
    "node": {
      "id": "bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3",
      "type": "card",
      "user": {
        "id": "21e65c4d-55e4-41be-97a1-ff38d8f3d945"
      }
    },
    "rate": "0.85620",
    "type": "card"
  },
  "fees": [{
    "amount": "0.04",
    "currency": "EUR",
    "percentage": "0.65",
    "target": "destination",
    "type": "exchange"
  }],
  "id": "2c326b15-7106-48be-a326-06f19e69746b",
  "message": null,
  "network": "uphold",
  "normalized": [{
    "amount": "6.56",
    "commission": "0.05",
    "currency": "USD",
    "fee": "0.00",
    "rate": "1.00000",
    "target": "destination"
  }],
  "origin": {
    "CardId": "48ce2ac5-c038-4426-b2f8-a2bdbcc93053",
    "amount": "6.56",
    "base": "6.56",
    "commission": "0.00",
    "currency": "USD",
    "description": "Angel Rath",
    "fee": "0.00",
    "isMember": true,
    "node": {
      "id": "48ce2ac5-c038-4426-b2f8-a2bdbcc93053",
      "type": "card",
      "user": {
        "id": "21e65c4d-55e4-41be-97a1-ff38d8f3d945"
      }
    },
    "rate": "1.16795",
    "sources": [{
      "amount": "6.56",
      "id": "3db4ef24-c529-421f-8e8f-eb9da1b9a582"
    }],
    "type": "card"
  },
  "params": {
    "currency": "USD",
    "margin": "0.65",
    "pair": "EURUSD",
    "progress": "1",
    "rate": "1.16795",
    "ttl": 18000,
    "type": "transfer"
  },
  "priority": "normal",
  "reference": null,
  "status": "completed",
  "type": "transfer"
}

Transactions record the movement of value into, within and out of the Uphold network. Transactions have the following properties:

Property	Description
application	The application that created the transaction.
createdAt	The date and time the transaction was initiated.
denomination	The funds to be transferred, as originally requested. See Denomination.
destination	The recipient of the funds. See Destination.
fees	The fees that were applied to the transaction. See Fees.
id	A unique ID on the Uphold Network associated with the transaction.
message	An optional note added when initiating the transaction. Expected to be human-readable prose, e.g. for providing additional information and context about the nature/purpose of the transaction.
network	The network of the transaction (`uphold` for internal transactions).
normalized	The transaction details in USD. See Normalized.
origin	The sender of the funds. See Origin.
params	Other parameters of this transaction. See Parameters.
priority	The priority of the transaction. Possible values are `normal` and `fast`.
reference	A reference code assigned to the transaction. Can be any string, up to 100 characters. This is not exposed to the user; a possible use case is to reference an external ID in another system.
status	The current status of the transaction. Possible values are `pending`, `processing`, `waiting`, `cancelled`, `failed` and `completed`.
type	The nature of the transaction. Possible values are `deposit`, `transfer` and `withdrawal`.

Denomination

The actual value being transacted is denominated in a certain currency, as expressed by the denomination field with the following properties:

Property	Description
amount	The amount to be transacted.
currency	The currency for said amount.
pair	The currency pair representing the denominated currency and the currency at `origin`.
rate	The quoted rate for converting between the denominated currency and the currency at `origin`.

If the denomination and origin are the same currency, the rate will be '1.00'.

Fees

The fees property contains an array of fees that were applied to the transaction. Each object in the array contains the following properties:

Property	Description
amount	The amount to be charged.
currency	The currency for said amount.
percentage	The percentage amount to be charged.
target	Can be `origin` or `destination` and determines where the fee was applied.
type	The type of fee. Can be one of: `deposit`, `exchange`, `network` or `withdrawal`.

Parameters

The params property associated with a transaction records additional meta data relating to the respective transaction. It contains the following properties:

Property	Description
currency	The currency in which the total commission is expressed.
margin	Uphold's commission expressed in percentage.
pair	The currency pair associated with any exchange that took place, if any.
progress	In case a transaction is coming in from the outside, how many confirmations have been received.
rate	The exchange rate of the transaction.
ttl	The time this quote is good for, in milliseconds.
type	The type of the transaction. Possible values are `deposit`, `transfer` and `withdrawal`.

Normalized

The normalized property contains the normalized amount and commission values in USD:

Property	Description
amount	The amount to be transacted.
commission	The total commission taken on this transaction, either at origin or at destination.
currency	The currency in which the amount and commission are expressed. The value is always `USD`.
fee	The normalized fee amount.
rate	The exchange rate for this currency pair.
target	Can be `origin` or `destination` and determines where the fee was applied.

Origin

The origin has properties regarding how the transaction affects the origin of the funds:

Property	Description
CardId	The ID of the card debited. Only visible to the user who sends the transaction.
amount	The amount debited, including commissions and fees.
base	The amount to debit, before commissions or fees.
commission	The commission charged by Uphold to process the transaction.
currency	The currency of the funds at the origin.
description	The name of the sender.
fee	The Bitcoin network Fee, if origin is in BTC but destination is not, or is a non-Uphold Bitcoin Address.
isMember	A boolean signaling if the origin user has completed the membership process.
node	The details about the transaction origin node.
rate	The rate for conversion between origin and destination, as expressed in the currency at origin (the inverse of `destination.rate`).
sources	The transactions where the value was originated from (id and amount).
type	The type of endpoint. Possible values are `card` and `external`.

Destination

The destination of a transaction has its own set of properties describing how the destination is affected, which include:

Property	Description
CardId	The ID of the card credited. Only visible to the user who receives the transaction.
amount	The amount credited, including commissions and fees.
base	The amount to credit, before commissions or fees.
commission	The commission charged by Uphold to process the transaction. Commissions are only charged when currency is converted into a different denomination.
currency	The denomination of the funds at the time they were sent/received.
description	The name of the recipient. In the case where money is sent via email, the description will contain the email address of the recipient.
fee	The Bitcoin network Fee, if destination is a BTC address but origin is not.
isMember	A boolean signaling if the destination user has completed the membership process.
node	The details about the transaction destination node.
rate	The rate for conversion between origin and destination, as expressed in the currency at destination (the inverse of `origin.rate`).
type	The type of endpoint. Possible values are `email`, `card` and `external`.

User Object

An example user encoded in JSON looks like this:

{
  "address": {
    "city": "Ryleighfort",
    "line1": "32167 Mohr Land",
    "line2": "Suite 257",
    "zipCode": "47890"
  },
  "balances": {
    "currencies": {
      "BTC": {
        "amount": "4500.00",
        "balance": "5.00",
        "currency": "USD",
        "rate": "900.00000"
      },
      "EUR": {
        "amount": "180.89",
        "balance": "154.88",
        "currency": "USD",
        "rate": "1.16795"
      },
      "USD": {
        "amount": "17710.05",
        "balance": "17710.05",
        "currency": "USD",
        "rate": "1.00000"
      }
    },
    "total": "22390.94"
  },
  "birthdate": "2000-09-27",
  "country": "US",
  "currencies": [
    "BTC",
    "CNY",
    "ETH",
    "EUR",
    "GBP",
    "JPY",
    "LTC",
    "USD",
    "XAU",
    "XRP"
  ],
  "email": "[email protected]",
  "firstName": "Malika",
  "id": "21e65c4d-55e4-41be-97a1-ff38d8f3d945",
  "lastName": "Koss",
  "memberAt": "2018-08-01T09:53:44.293Z",
  "name": "Malika Koss",
  "phones": [{
    "e164Masked": "+XXXXXXXXX66",
    "id": "abefe0b6-2f5d-45ba-97ac-3b07b08595a3",
    "internationalMasked": "+X XXX-XXX-XX66",
    "nationalMasked": "(XXX) XXX-XX66",
    "primary": true,
    "verified": true
  }],
  "settings": {
    "currency": "USD",
    "hasMarketingConsent": false,
    "hasNewsSubscription": false,
    "intl": {
      "dateTimeFormat": {
        "locale": "en-US"
      },
      "language": {
        "locale": "en-US"
      },
      "numberFormat": {
        "locale": "en-US"
      }
    },
    "otp": {
      "login": {
        "enabled": true
      },
      "transactions": {
        "send": {
          "enabled": true
        },
        "transfer": {
          "enabled": false
        },
        "withdraw": {
          "crypto": {
            "enabled": true
          }
        }
      },
      "vmc": {
        "enabled": true
      }
    }
  },
  "state": "US-UT",
  "status": "ok",
  "type": "individual",
  "verifications": {}
}

The user object contains most of the information we have on record relating to the currently logged in user.

Property	Description
memberAt	The date when the user became a verified member.

The memberAt field can be null if the user hasn't completed the membership process. Any information needed for membership will be included in the verifications field. Note that this is distinct from the pending user status, which is related to the initial signup process.

User Settings

otp.login.enabled - This will prompt the user to input an OTP token when creating an OAuth token.
otp.transactions.send.enabled - This will prompt the user to input an OTP token when creating a transaction to another user.
otp.transactions.transfer.enabled - This will prompt the user to input an OTP token when transacting between the user's own cards.
otp.transactions.withdraw.crypto.enabled - This will prompt the user to input an OTP token when withdrawing to the bitcoin network.
otp.vmc.enabled - This will prompt the user to input an OTP token when using VMCs.

User Status

We communicate a number of different user statuses through our API. At a high-level users can be in one of four statuses:

blocked - This status is present when a user has violated our terms of service.
ok - Everything is ay-ok.
pending - This status applies to a user that is in the process of creating an account; it means the signup process is not yet finalized.
restricted - This status means the user is allowed to login to the application, deposit or receive money, and perform trades, but they are not permitted to withdraw nor send money to other users. This status exists to allow users to satisfy additional data requirements. In this status users are unable to login or access the product.

User Verifications

The verifications field can help communicate the reasons for a given user status, or what's missing to complete the membership process. These verifications have permissible values and in some cases, an associated reason. Here is an overview of the verifications field:

Flag	Permissible Values	Reason	Description
address	null, required	n/a	Required for individual users.
birthdate	required	n/a	Whether the user needs to provide their date of birth.
customerDueDiligence	null, optional, required	n/a	CDD is required if the user is from an European country otherwise, it's optional.
documents	null, optional, required	identity-country-mismatch, invalid, missing	Required when the user must submit SSN or Tax ID.
email	unconfirmed	n/a	Whether the user needs to confirm their email.
identity	required, retry, review, running	n/a	The status of identity verification during the membership application process.
location	blocked, required	country, state	Whether the user has specified their location, which can be a blocked country/state.
permanentAddress	null, required	n/a	Required for non-US citizens with US residence.
phone	required, unconfirmed	n/a	The status of phone number verification.
terms	required	updated	Whether the user has accepted the latest version of the terms of service.
termsEquities	null, required	n/a	Required when the user hasn't accepted the terms of service for equities trading.
usTaxPayer	null, required	n/a	Required for non-US citizens with US residence.

Accounts

Uphold allows users to deposit value into a specific card from an external source (ACH account, debit/credit card or wire transfer) or withdraw to an external source (ACH account or wire transfer).

Whenever a deposit is made into an Uphold card, it will be automatically converted into the value determined by the card's denomination. Likewise, when a withdrawal is made, the currency will be converted to the currency of the destination account, thus minimizing fees and currency conversions.

We support the following account types:

Account type	Deposits supported?	Withdrawals supported?
ach	Yes	Yes
card	Yes	No
sepa	Yes	Yes

Please refer to our FAQ for estimated ACH transaction times, SEPA transaction times, fees and limits.

List Accounts

The basic request to this endpoint lists all accounts for the current user:

curl https://api.uphold.com/v0/me/accounts \
  -H "Authorization: Bearer <token>"

Example of filtering the list to show only accounts of the sepa or card types, and in the ok status:

curl 'https://api.uphold.com/v0/me/accounts?q=type:sepa,card%20status:ok'
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

[{
  "billing": {},
  "currency": "EUR",
  "id": "18843b6d-5a43-480f-8e2b-73b27d726bf0",
  "label": "Checking Account",
  "status": "ok",
  "type": "sepa"
},
{
  "billing": {
    "name": "Makenna Ortiz"
  },
  "brand": "visa",
  "currency": "USD",
  "id": "0874745c-f0bf-4973-a3d9-9832aeaae087",
  "label": "Savings Account",
  "status": "ok",
  "type": "card"
}]

Retrieves a list of accounts for the current user.

Request

GET https://api.uphold.com/v0/me/accounts

Requires the accounts:read scope for Uphold Connect applications.

You can filter the list of returned accounts using query string parameters. Supported filters are status: and type:, with either a single value or a comma-separated list. For a list of valid values for these parameters, refer to the Account Object documentation. Multiple filters can be used together, separated with a space. See the code to the right for an example.

Response

Returns an array of the current user's accounts.

Get Account Details

curl https://api.uphold.com/v0/me/accounts/18843b6d-5a43-480f-8e2b-73b27d726bf0 \
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

{
  "billing": {},
  "currency": "EUR",
  "id": "18843b6d-5a43-480f-8e2b-73b27d726bf0",
  "label": "Checking Account",
  "status": "ok",
  "type": "sepa"
}

Retrieves the details about a specific account.

Request

GET https://api.uphold.com/v0/me/accounts/:id

Requires the accounts:read scope for Uphold Connect applications.

Response

Returns a fully formed Account Object representing the requested account.

Adding credit/debit card accounts

The card details provided in this portion of the documentation are not real cards but specifically designed for Sandbox. These can be used to add card accounts to an Uphold wallet which will then allow for the testing of transactional flows.

Approved cards

The following is a list of valid card data that can be used to add a card account to an Uphold wallet for testing purposes.

Number	Brand	Type	Country	OCT settlement
4024007186645015	visa	credit	US	N/A
4024764449971519	visa	debit	US	instant
4111111111111111	visa	debit	PL	N/A
4242424242424242	visa	credit	GB	N/A
4243754271700719	visa	credit	US	N/A
4447336775378848	visa	debit	US	N/A
4452927588210665	visa	credit	US	N/A
4485040371536584	visa	credit	US	N/A
4485597929486000	visa	credit	US	N/A
4658584090000001	visa	debit	GB	N/A
4659105569051157	visa	debit	GB	instant
4659465888705671	visa	debit	GB	N/A
4757337282365488	visa	debit	DE	N/A
4921817844445119	visa	debit	GB	instant
5121073611487018	mastercard	credit	US	N/A
5259410220714099	mastercard	credit	US	N/A
5291144083573579	mastercard	credit	US	N/A
5318773012490080	mastercard	debit	US	instant
5355223761921186	mastercard	debit	GB	instant
5355224542121849	mastercard	debit	GB	N/A
5385308360135181	mastercard	credit	US	N/A
5436031030606378	mastercard	credit	MU	N/A
5502514549870410	mastercard	debit	FR	standard
5518832400606463	mastercard	debit	US	N/A
5569757734785691	mastercard	debit	SG	N/A
5573606426146833	mastercard	debit	GB	instant
5574357535453624	mastercard	debit	GB	N/A

3DS test cards

The following list contains data for 3DS-enabled cards and allows for forcing specific outcomes when testing both for the frictionless and the challenge flow.

Number	Brand	Type	Country	3DS flow	Result
5518832400606463	mastercard	debit	US	3DS2 challenge flow	authentication attempted
5291144083573579	mastercard	credit	US	3DS2 frictionless	error message during scheme communication
5121073611487018	mastercard	credit	US	3DS2 frictionless	no associated 3DS method url
5385308360135181	mastercard	credit	US	3DS2 challenge flow	authentication successfull
5259410220714099	mastercard	credit	US	3DS2 challenge flow	no associated 3DS method url
4242424242424242	visa	credit	GB	3DS2 challenge flow	authentication successfull
4485040371536584	visa	credit	US	3DS2 frictionless	authentication successfull
4484070000035519	visa	credit	GB	3DS2 frictionless	card not enrolled
4556574722325580	visa	credit	PT	3DS2 frictionless	authentication attempted
4447336775378848	visa	debit	US	3DS2 challenge flow	authentication could not be performed
4024007186645015	visa	credit	US	3DS2 frictionless	authentication could not be performed
4452927588210665	visa	credit	US	3DS2 frictionless	error message during scheme communication
4243754271700719	visa	credit	US	3DS2 challenge flow	not authenticated
4485597929486000	visa	credit	US	3DS2 challenge flow	no associated 3DS method url

Cards

Uphold uses the concept of a "card" as a store of value. Each card is denominated by a currency or store of value, and every card is automatically provisioned one or more addresses to which value can be sent. (Note that there can be multiple cards for the same currency.)

Whenever value flows into a card, Uphold automatically converts that value into the value determined by the card's denomination. In the world of bitcoin, for example, this allows one to preserve the original value sent by the sender, and shields the recipient from any volatility they might be exposed to by holding bitcoin directly. This also allows recipients of funds to normalize all incoming funds to a single store of value, regardless of how the value was originally sent.

List Cards

The basic request to this endpoint lists all cards for the current user:

curl https://api.uphold.com/v0/me/cards \
  -H "Authorization: Bearer <token>"

Example of filtering the list to show only starred cards denominated in BTC or EUR:

curl 'https://api.uphold.com/v0/me/cards?q=currency:BTC,EUR%20settings.starred:true'
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

[{
  "address": {
    "bitcoin": "mkZuBgFa4gAjJ2UckDA3Pms68rVBavAneF"
  },
  "available": "5.00",
  "balance": "5.00",
  "currency": "BTC",
  "id": "024e51fc-5513-4d82-882c-9b22024280cc",
  "label": "BTC card",
  "lastTransactionAt": "2018-08-01T09:53:44.617Z",
  "normalized": [{
    "available": "4500.00",
    "balance": "4500.00",
    "currency": "USD"
  }],
  "settings": {
    "position": 1,
    "protected": false,
    "starred": true
  }
},
{
  "address": {
    "bitcoin": "ms22VBPSahNTxHZNkYo2d4Rmw1Tgfx6ojr"
  },
  "available": "146.38",
  "balance": "146.38",
  "currency": "EUR",
  "id": "bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3",
  "label": "EUR card",
  "lastTransactionAt": "2018-08-01T09:53:51.258Z",
  "normalized": [{
    "available": "170.96",
    "balance": "170.96",
    "currency": "USD"
  }],
  "settings": {
    "position": 2,
    "protected": false,
    "starred": true
  }
}]

Retrieves a list of cards for the current user.

Request

GET https://api.uphold.com/v0/me/cards

Requires the cards:read scope for Uphold Connect applications.

You can filter the list of returned cards using query string parameters. Supported filters are currency: (which accepts a comma-separated list of currencies) and settings.starred: (which accepts true or false). Multiple filters can be used together, separated with a space. See the code to the right for an example.

This endpoint supports Pagination.

Response

Returns an array of the current user's cards.

Get Card Details

curl https://api.uphold.com/v0/me/cards/bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3 \
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

{
  "address": {
    "bitcoin": "ms22VBPSahNTxHZNkYo2d4Rmw1Tgfx6ojr"
  },
  "available": "146.38",
  "balance": "146.38",
  "currency": "EUR",
  "id": "bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3",
  "label": "EUR card",
  "lastTransactionAt": "2018-08-01T09:53:51.258Z",
  "normalized": [{
    "available": "170.96",
    "balance": "170.96",
    "currency": "USD"
  }],
  "settings": {
    "position": 2,
    "protected": false,
    "starred": true
  }
}

Retrieves the details about a specific card.

Request

GET https://api.uphold.com/v0/me/cards/:id

Requires the cards:read scope for Uphold Connect applications.

:id can either be the card ID or its bitcoin address and it must be owned by the user making the call.

Response

Returns the details associated with the card ID provided.

Create Card

curl https://api.uphold.com/v0/me/cards \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "label": "My New Card", "currency": "USD" }'

Request

POST https://api.uphold.com/v0/me/cards

Requires the cards:write scope for Uphold Connect applications.

Parameter	Description
currency	The currency to denominate the value stored by the card, represented by its code (e.g. "USD").
label	The display name of the card. Max length: 140 characters.

Response

Returns a fully formed Card Object representing the card created.

Update Card

curl https://api.uphold.com/v0/me/cards/37e002a7-8508-4268-a18c-7335a6ddf24b \
  -X PATCH \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "label": "My Updated Card" }'

Request

PATCH https://api.uphold.com/v0/me/cards/:id

Requires the cards:write scope for Uphold Connect applications.

Parameter	Description
label	The display name of the card. Max length: 140 characters.
settings	This property contains the following keys:
	`starred`: Indicates whether the card is starred or not.
	`DEPRECATED` `position`: The card's current position.

Response

Returns a fully formed Card Object representing the updated card.

Create Card Address

curl https://api.uphold.com/v0/me/cards/024e51fc-5513-4d82-882c-9b22024280cc/addresses \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "network": "ethereum" }'

The above command returns the following JSON:

{
  "id": "0x807A30A52180c4172ddCE90816bc951D004CF737",
  "network": "ethereum"
}

Generate an address for a card.

For the network xrp-ledger the response also returns the tag property, which is the corresponding Destination Tag.

For an XRP Ledger address, the following JSON is returned:

{
  "id": "rPjTZfLP3Qxwwd2xvXSALJzEFmmf7bEYgh",
  "network": "xrp-ledger",
  "tag": "1921241954"
}

Request

POST https://api.uphold.com/v0/me/cards/:id/addresses

Requires the cards:write scope for Uphold Connect applications.

Parameter	Description
network	The address network. Possible values are `bitcoin`, `bitcoin-cash`, `bitcoin-gold`, `dash`, `ethereum`, `interledger`, `litecoin` and `xrp-ledger`.

Response

Returns an object with the card address and the network.

List Card Addresses

curl https://api.uphold.com/v0/me/cards/37e002a7-8508-4268-a18c-7335a6ddf24b/addresses \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

The above command returns the following JSON:

[{
  "formats": [{
    "format": "pubkeyhash",
    "value": "mkZuBgFa4gAjJ2UckDA3Pms68rVBavAneF"
  }],
  "type": "bitcoin"
},
{
  "formats": [{
    "format": "pubkeyhash",
    "value": "0x807A30A52180c4172ddCE90816bc951D004CF737"
  }],
  "type": "ethereum"
},
{
  "formats": [{
    "format": "pubkeyhash",
    "value": "rPjTZfLP3Qxwwd2xvXSALJzEFmmf7bEYgh"
  }],
  "tag": "1921241954",
  "type": "xrp-ledger"
}]

Retrieves a list of addresses for a specific card.

The property tag is defined only to allow the XRP Ledger network to identify the card's Destination Tag.

Request

GET https://api.uphold.com/v0/me/cards/:id/addresses

Requires the cards:read scope for Uphold Connect applications.

Response

Returns an array with the card addresses and their networks.

Transactions

Create & Commit a Transaction

Step 1: Create the Transaction

curl https://api.uphold.com/v0/me/cards/a6d35fcd-xxxx-9c9d1dda6d57/transactions \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "denomination": { "amount": "0.1", "currency": "USD" }, "destination": "[email protected]" }'

The above command returns the following JSON:

{
  "application": null,
  "createdAt": "2018-08-01T09:53:47.020Z",
  "denomination": {
    "amount": "5.00",
    "currency": "GBP",
    "pair": "GBPUSD",
    "rate": "1.31"
  },
  "destination": {
    "CardId": "bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3",
    "amount": "5.57",
    "base": "5.61",
    "commission": "0.04",
    "currency": "EUR",
    "description": "Angel Rath",
    "fee": "0.00",
    "isMember": true,
    "node": {
      "id": "bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3",
      "type": "card",
      "user": {
        "id": "21e65c4d-55e4-41be-97a1-ff38d8f3d945"
      }
    },
    "rate": "0.85620",
    "type": "card"
  },
  "fees": [{
    "amount": "0.04",
    "currency": "EUR",
    "percentage": "0.65",
    "target": "destination",
    "type": "exchange"
  }],
  "id": "2c326b15-7106-48be-a326-06f19e69746b",
  "message": null,
  "network": "uphold",
  "normalized": [{
    "amount": "6.56",
    "commission": "0.05",
    "currency": "USD",
    "fee": "0.00",
    "rate": "1.00000",
    "target": "destination"
  }],
  "origin": {
    "CardId": "48ce2ac5-c038-4426-b2f8-a2bdbcc93053",
    "amount": "6.56",
    "base": "6.56",
    "commission": "0.00",
    "currency": "USD",
    "description": "Angel Rath",
    "fee": "0.00",
    "isMember": true,
    "node": {
      "id": "48ce2ac5-c038-4426-b2f8-a2bdbcc93053",
      "type": "card",
      "user": {
        "id": "21e65c4d-55e4-41be-97a1-ff38d8f3d945"
      }
    },
    "rate": "1.16795",
    "sources": [{
      "amount": "6.56",
      "id": "3db4ef24-c529-421f-8e8f-eb9da1b9a582"
    }],
    "type": "card"
  },
  "params": {
    "currency": "USD",
    "margin": "0.65",
    "pair": "EURUSD",
    "progress": "1",
    "rate": "1.16795",
    "ttl": 18000,
    "type": "transfer"
  },
  "priority": "normal",
  "reference": null,
  "status": "completed",
  "type": "transfer"
}

Step 2: Commit the Transaction

curl https://api.uphold.com/v0/me/cards/a6d35fcd-xxxx-9c9d1dda6d57/transactions/d51b4e4e-9827-40fb-8763-e0ea2880085b/commit \
  -X POST \
  -H "Authorization: Bearer <token>"

Returns a Transaction Object.

Step 1: Create Transaction

The first step is to prepare the transaction by specifying:

The currency to denominate the transaction by.
The amount of value to send in the denominated currency.
The origin of the transaction, which can be an account id in the case of a deposit.
The destination of the transaction, which can be in the form of a crypto network address, an email address, an account id, an application id, or a card id.
An optional message, which is shown to the user to provide additional context.
An optional reference code, which can be used as a unique identifier of the transaction in an external system, or for similar purposes.
An optional priority for the transaction ("normal" or "fast", with the default being "normal"), to signal the intent to fast-track its completion in exchange for a higher fee. This is currently only supported for the Dash network.

The following table describes the types of transactions currently supported:

Type	Origin	Destination
deposit	ACH, credit card or SEPA account id	Uphold card id
withdrawal	Uphold card id	ACH or SEPA account id, or cryptocurrency address
transfer	Uphold card id	Email address, Application id or Uphold card id

Upon preparing a transaction, a Transaction Object will be returned with a newly-generated id, and a status of pending.

Adding the query string parameter ?commit=true to this request will create and commit the transaction in a single step.

If the deposit origin is a CARD account ID and the query string parameter ?commit=true is set, you need to send the credit card's securityCode in the request body.

Request

POST https://api.uphold.com/v0/me/cards/:card/transactions

Requires any of the following scopes: transactions:deposit, transactions:transfer:application, transactions:transfer:others, transactions:transfer:self or transactions:withdraw for Uphold Connect applications. If creating with the query string parameter ?commit=true, the scope has to match the type of transaction being committed.

Response

Returns a Transaction Object.

If the deposit origin is a CARD account ID and the query string parameter ?commit=true is set, the transaction's params will include a redirect field with information of a redirect URI to be followed to complete the credit card deposit.

Step 2: Commit Transaction

Once a transaction has been created and a quote secured, commit the transaction using the previously returned id. An optional parameter message can also be sent which will overwrite the value currently stored in the transaction.

Once the transaction is committed, its status will change to processing.

If the transactions:commit:otp permission has been granted by the user, and an OTP is not provided with the request, you will get a 401 HTTP error, along with the HTTP header OTP-Token: Required. In that case, re-send the request, including the OTP verification code like so: OTP-Token: <OTP-Token>.

Request

POST https://api.uphold.com/v0/me/cards/:card/transactions/:id/commit

Requires any of the following scopes, based on the type of transaction being committed: transactions:deposit, transactions:transfer:application, transactions:transfer:others, transactions:transfer:self or transactions:withdraw for Uphold Connect applications.

If the deposit origin is a CARD account ID, you need to send the credit card's securityCode in the request body.

If the user has recently changed their password, they may be in a cool-down period where outbound transactions are not allowed, for security reasons. This results in a 400 HTTP error, with code password_reset_restriction. Your application must be prepared to handle this failure scenario.

Response

Returns a Transaction Object.

If the deposit origin is a CARD account ID, the transaction's params will include a redirect field with information of a redirect URI to be followed to complete the credit card deposit.

Specify destination currency

Example of creating a EUR to BTC transaction denominated in USD (i.e. buying 10 USD worth of BTC with and EUR card), by using the address of a EUR card as the origin in the URL parameter, and the address of an BTC card in the destination field, in the body of the request:

curl https://api.uphold.com/v0/me/cards/a6d35fcd-xxxx-9c9d1dda6d57/transactions \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "denomination": { "amount": "10", "currency": "USD" }, "destination": "e9225c6a-48b6-4e2e-ba36-beffdb5eb54e" }'

The response to the above request would look like the following JSON (truncated for conciseness):

{
  "denomination": {
    "amount": "10.00",
    "currency": "USD",
    "pair": "USDEUR",
    "rate": "0.84452"
  },
  "destination": {
    "CardId": "e9225c6a-48b6-4e2e-ba36-beffdb5eb54e",
    "amount": "0.00075846",
    "base": "0.00076651",
    "commission": "0.00000805",
    "currency": "BTC",
    "fee": "0.00",
    "isMember": true,
    "node": {
      "id": "e9225c6a-48b6-4e2e-ba36-beffdb5eb54e",
      "type": "card",
      "user": {
        "id": "5a5bc3a3-d945-47ce-8984-a569dff282af"
      }
    },
    "rate": "0.00009071",
    "type": "card"
  },
  "origin": {
    "CardId": "a6d35fcd-0ef3-41ed-acce-9c9d1dda6d57",
    "amount": "8.45",
    "base": "8.45",
    "commission": "0.00",
    "currency": "EUR",
    "fee": "0.00",
    "isMember": true,
    "node": {
      "id": "a6d35fcd-0ef3-41ed-acce-9c9d1dda6d57",
      "type": "card",
      "user": {
        "id": "5a5bc3a3-d945-47ce-8984-a569dff282af"
      }
    },
    "rate": "11023.87858",
    "sources": [],
    "type": "card"
  }
}

By using a card id as the destination of a transaction, it is possible to determine the destination currency, independently from the denomination. For example, to convert 10 USD worth of EUR to BTC, one could create a transaction from an EUR card to a BTC card, and denominate it in USD. An example is shown to the side.

Confirm a Credit Card Deposit

Example of redirect found in transaction.params for credit card deposit responses:

"redirect":{
  "url":"https://test.ppipe.net/connectors/demo/simulator.link?ndcid=8a8294175d602369015d73bf009f1808_7cbc8f0f400b421ab5bab3a8570a3fdf&REMOTEADDRESS=10.71.36.31",
  "parameters":[
    {
      "name":"TermUrl",
      "value":"https://test.ppipe.net/connectors/asyncresponse_simulator;jsessionid=89C6327A4B2FE425A8C375CF1C474521.uat01-vm-con04?asyncsource=THREEDSECURE&ndcid=8a8294175d602369015d73bf009f1808_7cbc8f0f400b421ab5bab3a8570a3fdf"
    },
    {
      "name":"PaReq",
      "value":"IT8ubu+5z4YupUCOEHKsbiPep8UzIAcPKJEjpwGlzD8#KioqKioqKioqKioqMDAwMCMxMi41MCBFVVIj"
    },
    {
      "name":"connector",
      "value":"THREEDSECURE"
    },
    {
      "name":"MD",
      "value":"8ac7a49f6a268259016a26953eca1b87"
    }
  ]
}

Example of a request for 3DSecure confirmation using the given redirect details:

-X POST 'https://test.ppipe.net/connectors/demo/simulator.link?ndcid=8a8294175d602369015d73bf009f1808_7cbc8f0f400b421ab5bab3a8570a3fdf&REMOTEADDRESS=10.71.36.31' \
-d 'MD=8ac7a49f6a268259016a26953eca1b87' \
-d 'TermUrl=https://test.ppipe.net/connectors/asyncresponse_simulator;jsessionid=89C6327A4B2FE425A8C375CF1C474521.uat01-vm-con04?asyncsource=THREEDSECURE&ndcid=8a8294175d602369015d73bf009f1808_7cbc8f0f400b421ab5bab3a8570a3fdf' \
-d 'PaReq=IT8ubu+5z4YupUCOEHKsbiPep8UzIAcPKJEjpwGlzD8#KioqKioqKioqKioqMDAwMCMxMi41MCBFVVIj' \
-d 'connector=THREEDSECURE'

When committing a transaction from a CARD account ID, the transaction's params will include a redirect field with information to be used to accept with 3DSecure and complete the credit card deposit.

The following table describes the data included in the returned redirect field:

Property	Description
parameters	List of objects with `name` and `value` properties to send to the 3DSecure confirmation request body.
url	The URL of the 3DSecure confirmation request.

This feature requires approval from Uphold's compliance team. Partners using this feature must not store the provided securityCode, in compliance with PCI DSS standards.

Request

POST <transaction.params.redirect.url>

Requires passing in the request body the parameters found in transaction.params.redirect.parameters in the format name=value.

Response

A webpage for 3DSecure confirmation for the user to interact with.

Beneficiary Information

As the cryptocurrency market grows and starts interacting more and more with the traditional finance world new rules are applied to the FinTech sector. As such, under the regulatory action of The Financial Action Task Force FATF, we are required to comply with the travel rule which requires us to "obtain, hold, and transmit required originator and beneficiary information in order to identify and report suspicious transactions, monitor the availability of information, take freezing actions, and prohibit transactions with designated persons and entities."

Example of a transaction creation payload including beneficiary and purpose fields:

{
  "beneficiary": {
    "address": {
      "city": "Ryleighfort",
      "country": "US",
      "line1": "32167 Mohr Land",
      "state": "US-CA",
      "zipCode": "47890"
    },
    "name": "Han Solo",
    "relationship": "child"
  },
  "denomination": {
    "amount": "3000",
    "currency": "USD"
  },
  "destination": "[email protected]",
  "purpose": "donations"
}

Parameter	Required	Description
beneficiary	yes/no	The transaction beneficiary information. See Beneficiary. Required for transfers to other users (invites included) and withdrawals above $3000 USD (or $1000 USD, if the origin user is from Arizona, United States). Note: ACH withdrawals do not require the beneficiary information to be sent. We only support personal bank accounts therefore the beneficiary (ACH account holder) is assumed to be the Uphold user who added that account.
purpose	yes/no	The reason for the transaction. Required for transactions in which the relationship is not set to `myself`. For business relationships, the possible values are: `business_expenses`, `business_travel`, `consultancy_expenses`, `education_expenses`, `family_expenses`, `funding_investments`, `gift_or_donations`, `invoice_payment`, `loan_payment`, `personal_expenses`, `salary_payments`, and `technology_expenses`. For personal relationships, the possible values are: `bill_payments`, `donations`, `expenses`, `gift`, `living_expenses`, `payment_for_goods_or_services`, and `supporting_family_internationally`.

Beneficiary

This beneficiary field has the following properties:

Parameter	Required	Description
address	yes/no	The transaction beneficiary address information. See Address. Required for invites and external beneficiaries.
name	yes/no	The beneficiary's full name. Required for invites and external beneficiaries. For all transactions, except those with `relationship` type `business`, the name must be composed of at least, 2 words with a minimum of 2 characters each, for the first and last word.
relationship	yes	Reflects the beneficiary's relationship to the transaction originator. Possible values are `business`, `child`, `co_worker`, `friend`, `myself`, `parent`, `sibling`.

Address

Property	Required	Description
city	yes	The beneficiary address city.
country	yes	The beneficiary address country.
line1	yes	The beneficiary address line 1.
line2	no	The beneficiary address line 2.
state	yes	The beneficiary address state.
zipCode	yes	The beneficiary address zip code.

Beneficiary Requirements

To obtain the transaction beneficiary requirements (or validate the beneficiary object) use the ?validate=true query parameter when creating the quote. This will generate a validation error if any required beneficiary information is missing. Otherwise, the transaction will fail at the commit step with a similar error message.

Please note that at this moment, even with the validate=true parameter, the validation is only performed if a beneficiary object is passed.

Example of including the beneficiary information when creating a quote, alongside the remaining transaction data:

curl 'https://api-sandbox.uphold.com/v0/me/cards/<card-id>/transactions' \
  -H 'Authorization: Bearer <bearer-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "beneficiary": {
      "address": {
        "city": "Ryleighfort",
        "country": "US",
        "line1": "32167 Mohr Land",
        "state": "US-CA",
        "zipCode": "47890"
      },
      "name": "Han Solo",
      "relationship": "child"
    },
    "denomination": {
      "amount": "3000",
      "currency": "USD"
    },
    "destination": "[email protected]",
    "purpose": "donations"
  }'

Example of adding the beneficiary information when committing a quote:

curl 'https://api-sandbox.uphold.com/v0/me/cards/<card-id>/transactions/<transaction-id>/commit' \
  -H 'Authorization: Bearer <bearer-token>' \
  -H 'Content-Type: application/json' \
  -H 'OTP-Token: <OTP-Token>' \
  -d '{
    "beneficiary": {
      "address": {
        "city": "Ryleighfort",
        "country": "US",
        "line1": "32167 Mohr Land",
        "state": "US-CA",
        "zipCode": "47890"
      },
      "name": "Han Solo",
      "relationship": "child"
    },
    "purpose": "donations"
  }'

In both cases, incomplete beneficiary information will be reported in a format similar to this:

{
  "code": "validation_failed",
  "errors": {
    "beneficiary": {
      "code": "validation_failed",
      "errors": {
        "name": [
          {
            "code": "required",
            "message": "This value is required"
          }
        ]
      }
    }
  }
}

Invalid beneficiary information will be reported like this:

{
  "code": "validation_failed",
  "errors": {
    "beneficiary": {
      "code": "validation_failed",
      "errors": {
        "name": [
          {
            "code": "invalid_beneficiary",
            "message": "The provided beneficiary is invalid"
          }
        ]
      }
    }
  }
}

For regulatory compliance reasons, the beneficiary name is checked by a sanctions screening process, and is expected to consist entirely of characters in the Latin, Cyrillic, Greek or Georgian alphabets, along with a limited set of special characters. These validations may result in an invalid_beneficiary error.

Cancel a Transaction

curl https://api.uphold.com/v0/me/cards/a6d35fcd-xxxx-9c9d1dda6d57/transactions/d51b4e4e-9827-40fb-8763-e0ea2880085b/cancel \
  -X POST \
  -H "Authorization: Bearer <token>"

Returns a Transaction Object.

Cancels a transaction that has not yet been redeemed.

Request

POST https://api.uphold.com/v0/me/cards/:card/transactions/:id/cancel

Requires the transactions:transfer:others scope for Uphold Connect applications.

Response

Returns a Transaction Object.

Only transactions with status waiting can be cancelled.

Resend a Transaction

curl https://api.uphold.com/v0/me/cards/a6d35fcd-xxxx-9c9d1dda6d57/transactions/d51b4e4e-9827-40fb-8763-e0ea2880085b/resend \
  -X POST \
  -H "Authorization: Bearer <token>"

Returns a Transaction Object.

Triggers a reminder for a transaction that hasn't been redeemed yet.

Request

POST https://api.uphold.com/v0/me/cards/:card/transactions/:id/resend

Requires the transactions:transfer:others scope for Uphold Connect applications.

Response

Returns a Transaction Object.

Only transactions with status waiting can be resent.

List User Transactions

curl https://api.uphold.com/v0/me/transactions \
  -X GET \
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

[{
  "application": null,
  "createdAt": "2018-08-01T09:53:47.020Z",
  "denomination": {
    "amount": "5.00",
    "currency": "GBP",
    "pair": "GBPUSD",
    "rate": "1.31"
  },
  "destination": {
    "CardId": "bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3",
    "amount": "5.57",
    "base": "5.61",
    "commission": "0.04",
    "currency": "EUR",
    "description": "Angel Rath",
    "fee": "0.00",
    "isMember": true,
    "node": {
      "id": "bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3",
      "type": "card",
      "user": {
        "id": "21e65c4d-55e4-41be-97a1-ff38d8f3d945"
      }
    },
    "rate": "0.85620",
    "type": "card"
  },
  "fees": [{
    "amount": "0.04",
    "currency": "EUR",
    "percentage": "0.65",
    "target": "destination",
    "type": "exchange"
  }],
  "id": "2c326b15-7106-48be-a326-06f19e69746b",
  "message": null,
  "network": "uphold",
  "normalized": [{
    "amount": "6.56",
    "commission": "0.05",
    "currency": "USD",
    "fee": "0.00",
    "rate": "1.00000",
    "target": "destination"
  }],
  "origin": {
    "CardId": "48ce2ac5-c038-4426-b2f8-a2bdbcc93053",
    "amount": "6.56",
    "base": "6.56",
    "commission": "0.00",
    "currency": "USD",
    "description": "Angel Rath",
    "fee": "0.00",
    "isMember": true,
    "node": {
      "id": "48ce2ac5-c038-4426-b2f8-a2bdbcc93053",
      "type": "card",
      "user": {
        "id": "21e65c4d-55e4-41be-97a1-ff38d8f3d945"
      }
    },
    "rate": "1.16795",
    "sources": [{
      "amount": "6.56",
      "id": "3db4ef24-c529-421f-8e8f-eb9da1b9a582"
    }],
    "type": "card"
  },
  "params": {
    "currency": "USD",
    "margin": "0.65",
    "pair": "EURUSD",
    "progress": "1",
    "rate": "1.16795",
    "ttl": 18000,
    "type": "transfer"
  },
  "priority": "normal",
  "reference": null,
  "status": "completed",
  "type": "transfer"
}]

Requests a list of committed transactions associated with the current user.

Request

GET https://api.uphold.com/v0/me/transactions

Requires the transactions:read scope for Uphold Connect applications.

This endpoint supports Pagination.

Response

Returns an array of Transaction Objects.

List Card Transactions

curl https://api.uphold.com/v0/me/cards/48ce2ac5-c038-4426-b2f8-a2bdbcc93053/transactions \
  -X GET \
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

[{
  "application": null,
  "createdAt": "2018-08-01T09:53:47.020Z",
  "denomination": {
    "amount": "5.00",
    "currency": "GBP",
    "pair": "GBPUSD",
    "rate": "1.31"
  },
  "destination": {
    "CardId": "bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3",
    "amount": "5.57",
    "base": "5.61",
    "commission": "0.04",
    "currency": "EUR",
    "description": "Angel Rath",
    "fee": "0.00",
    "isMember": true,
    "node": {
      "id": "bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3",
      "type": "card",
      "user": {
        "id": "21e65c4d-55e4-41be-97a1-ff38d8f3d945"
      }
    },
    "rate": "0.85620",
    "type": "card"
  },
  "fees": [{
    "amount": "0.04",
    "currency": "EUR",
    "percentage": "0.65",
    "target": "destination",
    "type": "exchange"
  }],
  "id": "2c326b15-7106-48be-a326-06f19e69746b",
  "message": null,
  "network": "uphold",
  "normalized": [{
    "amount": "6.56",
    "commission": "0.05",
    "currency": "USD",
    "fee": "0.00",
    "rate": "1.00000",
    "target": "destination"
  }],
  "origin": {
    "CardId": "48ce2ac5-c038-4426-b2f8-a2bdbcc93053",
    "amount": "6.56",
    "base": "6.56",
    "commission": "0.00",
    "currency": "USD",
    "description": "Angel Rath",
    "fee": "0.00",
    "isMember": true,
    "node": {
      "id": "48ce2ac5-c038-4426-b2f8-a2bdbcc93053",
      "type": "card",
      "user": {
        "id": "21e65c4d-55e4-41be-97a1-ff38d8f3d945"
      }
    },
    "rate": "1.16795",
    "sources": [{
      "amount": "6.56",
      "id": "3db4ef24-c529-421f-8e8f-eb9da1b9a582"
    }],
    "type": "card"
  },
  "params": {
    "currency": "USD",
    "margin": "0.65",
    "pair": "EURUSD",
    "progress": "1",
    "rate": "1.16795",
    "ttl": 18000,
    "type": "transfer"
  },
  "priority": "normal",
  "reference": null,
  "status": "completed",
  "type": "transfer"
}]

Retrieves a list of committed transactions associated with a specific card.

Request

GET https://api.uphold.com/v0/me/cards/:card/transactions

Requires the transactions:read scope for Uphold Connect applications.

This endpoint supports Pagination.

Response

Returns an array of Transaction Objects.

Get All Transactions (Public)

curl -X GET "https://api.uphold.com/v0/reserve/transactions"

The above command returns the following JSON (truncated for brevity):

[{
  "createdAt": "2014-09-25T19:19:51.201Z",
  "denomination": {
    "amount": "25.00",
    "currency": "USD",
    "pair": "USDUSD",
    "rate": "1.00"
  },
  "destination": {
    "CardId": "d42999c4-30c9-4a61-889c-62a4050bce88",
    "amount": "0.02777777",
    "base": "0.02777777",
    "commission": "0.00",
    "currency": "BTC",
    "description": "Nuno Sousa",
    "fee": "0.00",
    "rate": "0.00111111",
    "type": "card"
  },
  "fees": [{
    "amount": "0.00",
    "currency": "BTC",
    "percentage": "0.00",
    "target": "destination",
    "type": "exchange"
  }],
  "id": "63dc7ccb-0e57-400d-8ea7-7d903753801c",
  "message": null,
  "normalized": [{
    "amount": "22.94",
    "commission": "0.00",
    "currency": "EUR",
    "fee": "0.00",
    "rate": "0.91759"
  }],
  "origin": {
    "CardId": "f4dbc023-61bb-43e9-9ce6-7f34efd9e688",
    "amount": "25.00",
    "base": "25.00",
    "commission": "0.00",
    "currency": "USD",
    "description": "Nuno Sousa",
    "fee": "0.00",
    "rate": "900.00000",
    "sources": [{
      "amount": "25.00",
      "id": "4586e3f6-5fff-473f-b479-4e7ce2ba14cf"
    }],
    "type": "card"
  },
  "params": {
    "currency": "USD",
    "margin": "0.00",
    "pair": "BTCUSD",
    "progress": "1",
    "rate": "900.00000",
    "ttl": 7000,
    "type": "transfer"
  },
  "status": "completed",
  "type": "transfer"
},
{
  "createdAt": "2016-01-19T12:07:01.611Z",
  "denomination": {
    "amount": "0.01",
    "currency": "BTC",
    "pair": "BTCBTC",
    "rate": "1.00"
  },
  "destination": {
    "address": "n2eMqTT929pb1RDNuqEnxdaLau1rxy3efi",
    "amount": "0.01",
    "base": "0.01",
    "commission": "0.00",
    "currency": "BTC",
    "description": "n2eMqTT929pb1RDNuqEnxdaLau1rxy3efi",
    "fee": "0.00",
    "rate": "1.00",
    "type": "external"
  },
  "fees": [{
    "amount": "0.0002",
    "currency": "BTC",
    "target": "origin",
    "type": "network"
  }, {
    "amount": "0.00",
    "currency": "BTC",
    "percentage": "0.5",
    "target": "origin",
    "type": "withdrawal"
  }],
  "id": "99191bf6-52d8-4f29-92e8-676b68c9a85b",
  "message": null,
  "network": "bitcoin",
  "normalized": [{
    "amount": "9.18",
    "commission": "0.00",
    "currency": "USD",
    "fee": "0.18",
    "rate": "900.00000"
  }],
  "origin": {
    "CardId": "d42999c4-30c9-4a61-889c-62a4050bce88",
    "amount": "0.0102",
    "base": "0.01",
    "commission": "0.00",
    "currency": "BTC",
    "description": "Nuno Sousa",
    "fee": "0.0002",
    "rate": "1.00",
    "sources": [{
      "amount": "0.0102",
      "id": "390ed0ab-c014-43f3-868a-8ea3ea56025e"
    }],
    "type": "card"
  },
  "params": {
    "currency": "BTC",
    "margin": "0.00",
    "pair": "BTCBTC",
    "progress": "1",
    "rate": "1.00",
    "ttl": 7000,
    "type": "external/out"
  },
  "status": "completed",
  "type": "withdrawal"
}]

Request

GET https://api.uphold.com/v0/reserve/transactions

This endpoint supports Pagination.

Response

Returns an array of Transaction Objects.

Get Transaction (Public)

curl -X GET "https://api.uphold.com/v0/reserve/transactions/a97bb994-6e24-4a89-b653-e0a6d0bcf634"

The above command returns the following JSON:

{
  "application": null,
  "createdAt": "2014-08-27T00:01:11.616Z",
  "denomination": {
    "amount": "1.00",
    "currency": "USD",
    "pair": "USDUSD",
    "rate": "1.00"
  },
  "destination": {
    "amount": "1.00",
    "base": "1.00",
    "commission": "0.00",
    "currency": "USD",
    "fee": "0.00",
    "rate": "1.00"
  },
  "fees": [],
  "id": "a97bb994-6e24-4a89-b653-e0a6d0bcf634",
  "origin": {
    "amount": "1.00",
    "base": "1.00",
    "commission": "0.00",
    "currency": "USD",
    "fee": "0.00",
    "rate": "1.00",
    "sources": [{
      "amount": "1",
      "id": "35325c99-edeb-4625-9cd8-f56d4783c352"
    }]
  },
  "params": {
    "currency": "USD",
    "margin": "0.00",
    "pair": "USDUSD",
    "rate": "1.00"
  },
  "status": "cancelled",
  "type": "transfer"
}

Request

GET https://api.uphold.com/v0/reserve/transactions/:id

Response

Returns a Transaction Object.

Transaction Limit Errors

Example of a transaction that fails due to insufficient funds in the origin card:

curl 'https://api.uphold.com/v0/me/cards/a6d35fcd-xxxx-9c9d1dda6d57/transactions?commit=true' \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "denomination": { "amount": "1000", "currency": "EUR" }, "destination": "bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3" }'

The above command returns the following JSON:

{
  "code": "validation_failed",
  "errors": {
    "denomination": {
      "code": "validation_failed",
      "errors": {
        "amount": [
          {
            "code": "sufficient_funds",
            "message": "Not enough funds for the specified amount"
          }
        ]
      }
    }
  }
}

Example of a transaction that hits the maximum amount for the currency of the destination card:

curl 'https://api.uphold.com/v0/me/cards/a6d35fcd-xxxx-9c9d1dda6d57/transactions?commit=true' \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "denomination": { "amount": "1000", "currency": "BTC" }, "destination": "bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3" }'

The above command returns the following JSON (truncated for brevity):

{
  "code": "validation_failed",
  "errors": {
    "destination": {
      "code": "validation_failed",
      "errors": {
        "amount": [
          {
            "args": {
              "threshold": "25"
            },
            "code": "less_than_or_equal_to",
            "message": "This value should be less than or equal to 25"
          }
        ]
      }
    }
  }
}

When committing a transaction you may bump into various limits, such as the minimum or maximum amount for a given currency, maximum cumulative daily/weekly amount, etc. These are expressed as different errors, depending on the triggering conditions, as shown in the examples to the side; but in general, in such cases you will get a 400 HTTP error, and the response will have the code validation_failed and an errors field with the details.

For an overview of the current limits for transactions, refer to this article in our FAQ. Following the table in that page will allow you to validate transaction values on your side, before making API requests. Besides the limits listed there, it's also recommended to preemptively check a card's available balance to avoid hitting the "insufficient funds" error.

Users

Get User

curl "https://api.uphold.com/v0/me" \
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

{
  "address": {
    "city": "New Valentinstad",
    "line1": "80236 Ivy Loaf",
    "line2": "Apt. 366",
    "zipCode": "53059"
  },
  "balances": {
    "currencies": {
      "BTC": {
        "amount": "90.00",
        "balance": "0.1",
        "currency": "USD",
        "rate": "900.00000"
      }
    },
    "total": "90.00"
  },
  "birthdate": "2014-08-27",
  "country": "US",
  "currencies": [
    "BTC"
  ],
  "email": "[email protected]",
  "firstName": "Luke",
  "lastName": "Skywalker",
  "memberAt": "2015-07-10T15:36:20.288Z",
  "name": "Luke Skywalker",
  "settings": {
    "currency": "USD",
    "intl": {
      "dateTimeFormat": {
        "locale": "en-US"
      },
      "language": {
        "locale": "en-US"
      },
      "numberFormat": {
        "locale": "en-US"
      }
    },
    "otp": {
      "login": {
        "enabled": true
      },
      "transactions": {
        "send": {
          "enabled": true
        },
        "transfer": {
          "enabled": false
        },
        "withdraw": {
          "crypto": {
            "enabled": true
          }
        }
      }
    },
    "theme": "vintage"
  },
  "state": "WA",
  "status": "ok",
  "verifications": {}
}

Request

GET https://api.uphold.com/v0/me

Requires the user:read scope for Uphold Connect applications.

Response

Returns the data associated with the current user. See the user object documentation for details about the format of the response.

Cards

The cards property will be removed from the response. To access the cards of a given user please refer to the appropriate specific endpoint.

Get User Phone Numbers

curl "https://api.uphold.com/v0/me/phones" \
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

[{
  "e164Masked": "+XXXXXXXXX04",
  "id": "1d78aeb5-43ac-4ee8-8d28-1291b5d8355c",
  "internationalMasked": "+X XXX-XXX-XX04",
  "nationalMasked": "(XXX) XXX-XX04",
  "primary": "true",
  "verified": "true"
}]

Request

GET https://api.uphold.com/v0/me/phones

Response

Returns an array of all the phone numbers associated with the current user.

Countries

List Countries

This endpoint returns the data for all countries and territories registered in our platform (about 250 of them, without pagination).

Each entry contains several fields of information, which are described in the table below:

Property	Description
alpha2	The ISO 3166-1 alpha-2 code for the country or territory, e.g. "US" or "FR".
currency	The ISO 4217 code of the official currency used in the country, e.g. "EUR" or "GBP".
name	The common or official name of the country or territory, e.g. "Portugal" or "North Macedonia".
phone	The country calling code (international phone number prefix) and an example phone number.
status	The status of the country regarding Uphold's regulatory compliance rules. Can be either "ok" or "blocked".

Request

Example request to get the list of countries and territories:

curl https://api.uphold.com/v0/countries

GET https://api.uphold.com/v0/countries

Response

The above command returns the following JSON (truncated for conciseness):

[
  {
    "alpha2": "AD",
    "currency": "EUR",
    "name": "Andorra",
    "phone": {
      "code": "376",
      "example": "312 345"
    },
    "status": "ok"
  },
  {
    "alpha2": "PT",
    "currency": "EUR",
    "name": "Portugal",
    "phone": {
      "code": "351",
      "example": "912 345 678"
    },
    "status": "ok"
  },
  {
    "alpha2": "ZW",
    "currency": "ZWL",
    "name": "Zimbabwe",
    "phone": {
      "code": "263",
      "example": "071 123 4567"
    },
    "status": "ok"
  }
]

Returns an array of country objects as described in the table above.

Get Country

This endpoint allows fetching the data for a specific country, given its ISO 3166-1 alpha-2 code.

Request

Example request to get the data for a specific country:

curl https://api.uphold.com/v0/countries/US

GET https://api.uphold.com/v0/countries/:country

Response

The above command returns the following JSON:

{
  "alpha2": "US",
  "currency": "USD",
  "name": "United States of America",
  "phone": {
    "code": "1",
    "example": "(201) 555-0123"
  },
  "status": "ok"
}

Returns a single country object as described in the table above.

Get Country Payments

This endpoint returns a list of available payment methods and corresponding supported currencies for a given country or territory.

Request

Example request to get the payment methods available in a given country:

curl https://api.uphold.com/v0/countries/PT/payments

GET https://api.uphold.com/v0/countries/:country/payments

Response

The above command returns the following JSON:

[
  {
    "currency": "EUR",
    "method": "card"
  },
  {
    "currency": "EUR",
    "method": "sepa"
  },
  {
    "currency": "GBP",
    "method": "card"
  },
  {
    "currency": "USD",
    "method": "card"
  }
]

Returns an array of payment objects containing two fields:

Property	Description
currency	The ISO 4217 code of the currency supported for this payment method in this country.
method	The type of payment method. One of "ach", "card", or "sepa".

Each method+currency pair is represented as a separate entry in this list. For example, if both USD and EUR are supported for the card method, the list will contain two entries, one with the USD-card pair, and one with the EUR-card pair.

Get Country Subdivisions

This endpoint provides a list of the subdivisions of a given country.

Request

Example request to get the subdivisions of a given country:

curl https://api.uphold.com/v0/countries/BA/subdivisions

GET https://api.uphold.com/v0/countries/:country/subdivisions

Response

The above command returns the following JSON:

[
  {
    "code": "BA-BIH",
    "name": "Federacija Bosne i Hercegovine"
  },
  {
    "code": "BA-BRC",
    "name": "Brčko distrikt"
  },
  {
    "code": "BA-SRP",
    "name": "Republika Srpska"
  }
]

Returns an array of subdivision objects, containing the official name and the corresponding ISO 3166-2 code. If the country contains no subdivisions, an empty array is returned.

Transparency

The following section outlines a system for how Uphold will provide the transparency our members require in order to ascertain the solvency of the reserve we operate to protect the value entrusted to us by our Members.

We will provide our members with access to two different resources. The first is the Uphold Ledger, or "Reserveledger" as we call it. The Reserveledger is a real-time listing of all the company's assets and liabilities. Each entry in the ledger can reference one or more transactions that a user can inquire about and obtain the details of via the second key resource: the Reservechain.

The Reserveledger

Our ledger provides a detailed record of the obligations (a.k.a. "liabilities") flowing into our network via our members, and the resulting changes we as a company make to the assets in our reserve to secure the value of those obligations.

The ledger is made up of "entries", each of which contains information about the change to an asset, a liability, or both, and references the related transactions that affected the change whenever possible.

Frequently one may find that changes to the Reserve's assets and liabilities are not made in lock step with one another, and that the Reserve may accrue liabilities of one asset type or another, and then have those liabilities offset by a single change to the Reserve's assets.

Request

curl https://api.uphold.com/v0/reserve/ledger

GET https://api.uphold.com/v0/reserve/ledger

This endpoint supports Pagination.

To access this endpoint, an API key is required.

Deposits

The following entry shows how a deposit of 0.5 bitcoin by a user would be encoded on the Reserveledger. Every deposit results in two entries in the ledger. The first records the acquisition of a liability, and the second the genesis of an asset. Specifically, it shows the creation of 0.5 bitcoin as an obligation to the user, plus the acquisition of 0.5 bitcoin as an asset.

{
  "TransactionId": "e205b50e-6649-416d-82c1-98f0ba44dcd9",
  "createdAt": "2014-10-08T12:26:29.844Z",
  "in": {
    "amount": "0.5",
    "currency": "BTC"
  },
  "out": {
    "amount": "0.00",
    "currency": "BTC"
  },
  "type": "liability"
},
{
  "createdAt": "2014-10-08T12:26:29.844Z",
  "in": {
    "amount": "0.5",
    "currency": "BTC"
  },
  "out": {
    "amount": "0.00",
    "currency": "BTC"
  },
  "type": "asset"
}

Transfer of Value

The entry below shows how a user transferring 1.3 bitcoin to a "dollar card", effectively exchanging bitcoin for dollars, would be encoded on the ledger. In this entry, two liabilities are affected. The first is a loss of 1.3 BTC as an obligation, and the second is a gain of $507.51 USD as an obligation. Which makes sense: when a user transfers the bitcoin to their dollar card, Uphold no longer owes them that bitcoin. Instead, Uphold owes them the $507.51 they exchanged for that bitcoin.

{
  "TransactionId": "1571fbef-d34e-447c-9b6e-4ad775953082",
  "createdAt": "2014-09-30T20:29:36.575Z"
  "in": {
    "amount": "507.51",
    "currency": "USD"
  },
  "out": {
    "amount": "1.3",
    "currency": "BTC"
  },
  "type": "liability"
}

This transfer of value affects our liabilities immediately and in real-time, and thus is reflected in real-time in the ledger. But when our obligations to our members change, a possible imbalance in our Reserve is introduced. To compensate for this, we must make changes to the assets as well. These changes to our assets may or may not happen in real-time. This would therefore be recorded in our ledger at some point in the future as follows:

{
  "createdAt": "2014-09-30T20:29:36.575Z",
  "in": {
    "amount": "507.51",
    "currency": "USD"
  },
  "out": {
    "amount": "1.3",
    "currency": "BTC"
  },
  "type": "asset"
}

The examples above are nearly identical from one another due to the simplicity of the use case it elucidates. Consider however that when operating normally it is likely that a series of changes to our liabilities will be aggregated and accounted for in a single change to our assets in order to restore balance to the reserve.

Withdrawal of Bitcoin

When value is removed from the Reserve, two entries are added. One accounting for the change in assets, and the other for the change in liabilities. The following entry shows how a user transmitting some bitcoin to an external network/wallet would be encoded on the ledger. It shows the removal of a liability of bitcoin to the user, and the subsequent removal of bitcoin as an asset.

{
  "createdAt": "2014-10-08T06:53:51.080Z",
  "in": {
    "amount": "0.00",
    "currency": "BTC"
  },
  "out": {
    "amount": "0.10359178",
    "currency": "BTC"
  },
  "type": "asset"
},
{
  "TransactionId": "6ab1f3e8-3b84-40b0-aec7-8008117c9f86",
  "createdAt": "2014-10-08T06:53:51.080Z",
  "in": {
    "amount": "0.00",
    "currency": "BTC"
  },
  "out": {
    "amount": "0.10359178",
    "currency": "BTC"
  },
  "type": "liability"
}

Reallocation of Assets

Uphold may decide to secure the value of its Reserve by holding value in asset classes which may or may not correlate to how our liabilities are denominated among our members. For example, Uphold may wish to convert $1,000,000 in cash into a security of equal value. These changes to the Reserve do not relate to any specific transaction, but need to be accounted for nonetheless. What follows is how we could encode shifting 1M dollars into a US Treasury Bill. Take note that we can optionally include additional data relating to the asset class.

{
  "createdAt": "2014-10-08T06:53:51.080Z"
  "in": {
    "amount": "1",
    "currency": "T-Bill"
    "meta": {
      "cusip": 345370860,
      "maturityDate": "2016-05-01 00:00:00 UTC",
      "principal": 1000000,
      "rate": 1.5
    }
  },
  "out": {
    amount: "1000000",
    currency: "USD"
  },
  "type": "asset"
}

The Reservechain

Uphold's Reservechain is a record of all of the transactions made by its Members that move value through the network. It is a "chain" in that any value moved in a transaction can be easily traced back to it's origin.

At a high level, each transaction in the Reservechain contains the following key pieces of information:

a unique ID
the entity initiating the transaction
the entity receiving the value being moved
a collection of value stored on the network from which the value for current transaction is derived
all relevant exchange data associated with the transaction, including the quoted exchange rates, Uphold's commission, etc.

Traceability

Just like a block chain, the Reservechain is both completely transparent, and traceable. For a transaction to be traceable, the value encapsulated by the transaction must reference all the places within the chain where that value is drawn from. This is done by providing a list of transaction IDs, and the value drawn from each. By following these transactions you walk backwards down different paths of the Reservechain until you ultimately find a genesis point for all value accounted for in the transaction.

Security and Privacy

All transactions are made public, but specific details about the transaction may be withheld from parties who were not a party to said transaction. To control this, we require developers to authenticate prior to retrieving privileged information relating to a transaction.

Deposits

A deposit relates to two things: the adding of value into the Reservechain from the outside, and the creation of a new obligation to a user.

Given that this is a point in the chain at which there is a genesis of value, there are no subsequent transactions within the Reservechain to link backwards to. However, we will provide a link to the external authority documenting the source of the value whenever possible.

{
  "createdAt": "2014-10-08T12:26:29.807Z"
  "denomination": {
    "amount": "0.5",
    "currency": "BTC"
  },
  "destination": {
    "amount": "0.5",
    "base": "0.5",
    "commission": "0.00",
    "currency": "BTC",
    "fee": "0.00",
    "rate": "1.00"
  },
  "id": "e205b50e-6649-416d-82c1-98f0ba44dcd9",
  "origin": {
    "amount": "0.5",
    "base": "0.5",
    "commission": "0.00",
    "currency": "BTC",
    "fee": "0.00",
    "rate": "1.00",
    "sources": []
  },
  "params": {
    "currency": "BTC",
    "margin": "0.00",
    "pair": "BTCBTC",
    "rate": "1.00",
    "txid": "ffb51cc62944f334aa56ef7339a8df9ba08c712d9db609207f2f1f2105b914b2"
  },
  "status": "completed",
  "type": "deposit"
}

Withdrawals

Withdrawal documents the flow of assets out of the system. The destination of the transaction would refer as completely as it can to any external sources that the Uphold transaction can be correlated against/with.

Withdrawals also account for value leaving the Reservechain, and is thus a terminus point with regards to traceability.

{
  "createdAt": "2014-10-08T06:53:51.060Z",
  "denomination": {
    "amount": "34.00",
    "currency": "USD"
  },
  "destination": {
    "address": "1BSrDxeTL9ViJBrAb1QHjK2wsGShjSGVeb",
    "amount": "0.10349178",
    "base": "0.10349178",
    "commission": "0.00",
    "currency": "BTC",
    "fee": "0.00",
    "rate": "1.00"
  },
  "id": "6ab1f3e8-3b84-40b0-aec7-8008117c9f86",
  "origin": {
    "amount": "0.10359178",
    "base": "0.10349178",
    "commission": "0.00",
    "currency": "BTC",
    "fee": "0.0001",
    "rate": "1.00",
    "sources": [{
      "amount": "0.10359178",
      "id": "33eef226-1c1e-4b38-be2f-28d9a57aecdb"
    }]
  },
  "params": {
    "currency": "BTC",
    "margin": "0.00",
    "pair": "BTCBTC",
    "rate": "1.00",
    "txid": "5ee2a05a4af8bef5090ee8974798c097a7d6a75be7564d17e6a330bc1c434bab"
  },
  "status": "completed",
  "type": "withdrawal"
}

Transfers

A transfer documents movement of value within our network, either between two parties or two denominations, or both.

{
  "createdAt": "2014-09-30T20:29:36.458Z",
  "denomination": {
    "amount": "1.3",
    "currency": "BTC"
  },
  "destination": {
    "amount": "507.51",
    "base": "509.81",
    "commission": "2.30",
    "currency": "USD",
    "fee": "0.00",
    "rate": "392.16000"
  },
  "id": "1571fbef-d34e-447c-9b6e-4ad775953082",
  "origin": {
    "amount": "1.3001",
    "base": "1.3",
    "commission": "0.00",
    "currency": "BTC",
    "fee": "0.0001",
    "rate": "0.00255",
    "sources": [{
      "amount": "0.73327414",
      "id": "61cdccdf-cb6e-414e-aafc-7c42dc375cf6"
    }, {
      "amount": "0.56682586",
      "id": "34f87520-49a4-4f46-8ee0-ba0522c06aa1"
    }]
  },
  "params": {
    "currency": "USD",
    "margin": "0.45",
    "pair": "BTCUSD",
    "rate": "392.16000",
    "txid": "1946783b396998f8f91c984431ecfecff6d0a72db68b32d0873c1024c7279254"
  },
  "status": "completed",
  "type": "transfer"
}

Privacy

The Reservechain is a public resource, and is 100% anonymous. At no point does the Reservechain expose any personally identifiable information, or any information that could be directly tied to an identity with our network.

We may disclose personally identifiable information to those who were a party to a transaction by way of the protected List User Transactions and List Card Transactions endpoints.

Pagination

Collection endpoints with large dataset supports Range Pagination Headers, using the Range and Content-Range entity-headers.

Request

You can provide the Range header in your request to specify how many items you want to retrieve. The maximum number of items per page is 50. That is also the default value if you leave it unspecified.

For example, here's how you'd fetch the five most recent transactions associated with the current user. Note that the items are indexed from zero:

curl https://api.uphold.com/v0/me/transactions \
  -H "Authorization: Bearer <token>" \
  -H "Range: items=0-4"

Response

The endpoints that support pagination will return a Content-Range header. For instance, if you make a request with the Range: items=0-4 header, the response will contain the header Content-Range: items 0-4/<total>, where <total> will be the total number of items available for listing.

If the Range header is malformed or if the range cannot be satisfied, you will receive a 412 HTTP error or a 416 HTTP error, respectively.

Rate Limits

The API applies rate limits based on the number of requests per a predefined interval (i.e. a time-window). We currently do not differentiate between authenticated and unauthenticated requests. The global rate limit takes into account the remote client IP only.

We plan on changing this policy in the future to one that limits on an account-by-account basis. For now, please be advised that those operating from corporate networks may hit their limit faster, given that everyone may present the same IP address to our network.

Some endpoints have stricter rules as it relates to rate limits. These endpoints may additionally take into consideration the user's account or email address. For example, there can be 5 requests per 60 minute time period per IP to the /password/forgot endpoint; but multiple IPs can only make 5 requests per 60 minute time period per user account (e.g. [email protected]).

The following table indicates the current rate limits:

Endpoint	Requests (per IP) / window	Requests (per user) / window
Global	250 / 1-min window	N/A
POST /me/confirm	10 / 10-min window	N/A
POST /me/reports	10 / 10-min window	10 / 10-min window
POST /oauth2/token	50 / 5-min window	50 / 5-min window
POST /password/change	5 / 60-min window	5 / 60-min window
POST /password/forgot	5 / 60-min window	5 / 60-min window
POST /password/reset	5 / 60-min window	N/A

Response Headers

The standard HTTP Retry-After header field will be appended when the rate limit is exhausted, and indicates, in delta-seconds, how long until the rate limit window is reset.

Example request:

curl -I -X GET "https://api.uphold.com/v0/ticker"

When the API limit is reached, a 429 HTTP error is returned with the aforementioned Retry-After header:

Example response for a rate limited request:

HTTP/1.1 429 Too Many Requests

Retry-After: 85

In this this example, the request could be retried in 1 minute and 25 seconds.

If you think you have a legitimate use-case for increased rate limits, please contact us.

Errors

Uphold API uses the following error codes:

Code	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
412	Precondition Failed
416	Range Not Satisfiable
429	Too Many Requests
500	Internal Server Error
503	Service Unavailable

Support

Need help, or have a question? Contact [email protected].