NAV

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

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)

Powered by Uphold
small (199x40), large (398x80), vector (SVG)

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

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

Powered by Uphold
small (199x40), large (398x80), 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.

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

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

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:

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:

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.

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.

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.

User Settings

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:

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

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

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
5502514549870410 mastercard debit FR standard
5355223761921186 mastercard debit GB instant
5573606426146833 mastercard debit GB instant
5318773012490080 mastercard debit US instant
4921817844445119 visa debit GB instant
4659105569051157 visa debit GB instant
4024764449971519 visa debit US instant
5355224542121849 mastercard debit GB N/A
5574357535453624 mastercard debit GB N/A
5573606426146833 mastercard debit GB N/A
5355223761921186 mastercard debit GB N/A
5436031030606378 mastercard credit MU N/A
5518832400606463 mastercard debit US N/A
5385308360135181 mastercard credit US N/A
5259410220714099 mastercard credit US N/A
5121073611487018 mastercard credit US N/A
5291144083573579 mastercard credit US N/A
5569757734785691 mastercard debit SG N/A
4658584090000001 visa debit GB N/A
4659465888705671 visa debit GB N/A
4242424242424242 visa credit GB N/A
4447336775378848 visa debit US N/A
4111111111111111 visa debit PL N/A
4485040371536584 visa credit US N/A
4024007186645015 visa credit US N/A
4452927588210665 visa credit US N/A
4485597929486000 visa credit US N/A
4243754271700719 visa credit US N/A
4024007181869214 visa credit US 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

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

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

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

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 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

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.

Request

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

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 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.

Request

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

Response

Returns a Transaction Object.

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.

Request

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

Response

Returns a Transaction Object.

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.

Request

POST <transaction.params.redirect.url>

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.

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"
          }
        ]
      }
    }
  }
}

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

Response

Returns a Transaction Object.

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

Response

Returns a Transaction Object.

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

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

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"
}]

See also: Transparency: Reservechain

Requests the public view of all transactions in the reserve.

To access this endpoint, an API key is required.

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"
}

See also: Transparency: Reservechain

Requests the public view of a specific transaction.

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

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".

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:

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 10 requests per 10 minute time period per IP to the /password/forgot endpoint; but multiple IPs can only make 3 requests per 5 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 500 / 5-min window N/A
POST /cards/:card/transactions 300 / 5-min window N/A
POST /cards/:card/transactions/:id/commit 300 / 5-min window N/A
POST /password/forgot 10 / 10-min window 3 / 5-min window
POST /users 10 / 10-min window N/A

Response Headers

The current rate limit in effect is explained via custom HTTP headers as described in the table below. Additionally, 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.

Header Description
Rate-Limit-Remaining The number of requests remaining in the current window duration
Rate-Limit-Reset The time, in UTC epoch seconds, until the end of the current window duration
Rate-Limit-Total The total number of requests possible in the current window duration
Retry-After The time, in seconds, until the end of the current window duration

Example request:

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

Rate limit details on response headers:

Rate-Limit-Remaining: 499
Rate-Limit-Reset: 1422288284
Rate-Limit-Total: 500

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

Rate-Limit-Remaining: 0
Rate-Limit-Reset: 1422288284
Rate-Limit-Total: 300
Retry-After: 85

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

Alternatively, the Rate-Limit-Reset header could also be used to calculate when to retry the request:

Parsing Rate-Limit-Reset:

console.log(new Date(1422288199 * 1000));

// Mon Jan 26 2015 16:30:11 GMT+0000 (WET)

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].