NAV
cURL

Introduction

Welcome to the Uphold API, we’re glad to have you! Provided here is all the documentation you need to help you create custom and revolutionary new services powered by the Uphold Platform. With your ingenuity, together we can serve the needs of individuals and organizations across the globe and change the financial services ecosystem forever.

Client Libraries

The follow libraries are available:

We are actively looking for developers to contribute Uphold client libraries for a variety of platforms and languages. If you have written a library, please share a link to the github repository with us at [email protected] so that we can promote it here, and collaborate with you on its further development.

API Changes

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

The official changelog is currently 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 following scopes are supported by the API:

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.
contacts:read Can view all contacts and their information.
contacts:write Can create and update any contact.
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 Button
small (125x41), large (249x82)

Connect Button
small (206x41), large (412x82)

Connect Button
small (199x41), large (397x82)

Connect Button
small (125x41), large (249x82)

Connect Button
small (206x41), large (412x82)

Connect Button
small (199x41), large (397x82)

Connect Button
small (124x40), large (247x80)

Connect Button
small (205x40), large (410x80)

Connect Button
small (198x40), large (395x80)

Connect Button
small (125x41), large (249x82)

Connect Button
small (206x41), large (412x82)

Connect Button
small (199x41), large (397x82)

Connect Button
small (129x50), large (258x100)

Connect Button
small (129x50), large (258x100)

Connect Button
small (129x50), large (258x100)

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 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://uphold.com/authorize/<client_id>

Or for sandbox applications:

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

Supported query parameters:

Parameter Required Description
intention no 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.
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

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 username/password combination, i.e. remain secret and never shared with third parties. PATs can be issued and revoked individually.

Creating a PAT

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

curl https://api.uphold.com/v0/me/tokens \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "OTP-Token: <OTP-Token>" \
  -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 username or email and password:

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

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

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

Currencies

In Uphold’s API, we frequently call for a currency as an input or output. We represent all such currencies and stores of value by a three letter code as per ISO 4217 codes.

In our Knowledge Base you will always find the most recent and up-to-date list of the currencies we support, along with the three letter abbreviation you can use when referring to the currency within the API.

Tickers

Developers can query at any time 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"
}]

This method allows developers to find all exchanges 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.

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, failed.
type The type of the account. Possible values are: card, sepa.

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.
settings Contains the card’s current position and whether the card is starred or not.
normalized Contains the normalized available and balance values in the currency set by the user in the settings.

Contact Object

An example contact encoded in JSON looks like this:

{
  "addresses": [
    "mtRwYWGKe1hYqNJ5fSTogXWPnFxoQrPYo6"
  ],
  "company": "Independent",
  "emails": [
    "[email protected]"
  ],
  "firstName": "Han",
  "id": "c4db98e4-c9e1-46dc-a927-17a26fb9772c",
  "lastName": "Solo",
  "name": "Han Solo"
}
Property Description
addresses An array of known addresses associated with this contact.
company The company of this contact provided by the user.
emails An array of known email addresses associated with this contact.
firstName The first name of this contact provided by the user.
id A unique ID in the Uphold network identifying the contact.
lastName The last name of this contact provided by the user.
name The display name of the contact created by joining the first and last names.

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, e.g. USD, GBP, EUR, 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.

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",
        "username": "angelrath"
      }
    },
    "rate": "0.85620",
    "type": "card",
    "username": "angelrath"
  },
  "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",
        "username": "angelrath"
      }
    },
    "rate": "1.16795",
    "sources": [{
      "amount": "6.56",
      "id": "3db4ef24-c529-421f-8e8f-eb9da1b9a582"
    }],
    "type": "card",
    "username": "angelrath"
  },
  "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.
id A unique ID on the Uphold Network associated with the transaction.
type The nature of the transaction. Possible values are deposit, transfer and withdrawal.
message A message or note provided by the user at the time the transaction was initiated, with the intent of communicating additional information and context about the nature/purpose of the transaction.
denomination The funds to be transferred, as originally requested. See Denomination.
fees The fees that were applied to the transaction. See Fees.
status The current status of the transaction. Possible values are: pending, waiting, cancelled or completed.
params Other parameters of this transaction. See Parameters.
createdAt The date and time the transaction was initiated.
network The network of the transaction (uphold for internal transactions).
normalized The transaction details in USD. See Normalized.
priority The priority of the transaction. Possible values are normal and fast.
reference A reference assigned to the transaction.
origin The sender of the funds. See Origin.
destination The recipient of the funds. See Destination.

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 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’.
username The username from the user that performed the transaction.

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": {
      "BCH": {
        "amount": "4500.00",
        "balance": "5.00",
        "currency": "USD",
        "rate": "900.00000"
      },
      "BTC": {
        "amount": "4500.00",
        "balance": "5.00",
        "currency": "USD",
        "rate": "900.00000"
      },
      "BTG": {
        "amount": "57.65",
        "balance": "5.00",
        "currency": "USD",
        "rate": "11.52945"
      },
      "CNY": {
        "amount": "90.84",
        "balance": "600.00",
        "currency": "USD",
        "rate": "0.15140"
      },
      "DASH": {
        "amount": "57.65",
        "balance": "5.00",
        "currency": "USD",
        "rate": "11.52945"
      },
      "ETH": {
        "amount": "5000.00",
        "balance": "10.00",
        "currency": "USD",
        "rate": "500.00000"
      },
      "EUR": {
        "amount": "180.89",
        "balance": "154.88",
        "currency": "USD",
        "rate": "1.16795"
      },
      "GBP": {
        "amount": "1174.94",
        "balance": "895.59",
        "currency": "USD",
        "rate": "1.31192"
      },
      "LTC": {
        "amount": "1300.00",
        "balance": "10.00",
        "currency": "USD",
        "rate": "130.00000"
      },
      "MXN": {
        "amount": "7.88",
        "balance": "149.99",
        "currency": "USD",
        "rate": "0.05257"
      },
      "USD": {
        "amount": "97710.05",
        "balance": "97710.05",
        "currency": "USD",
        "rate": "1.00000"
      },
      "VOX": {
        "amount": "31.60",
        "balance": "2.74066412",
        "currency": "USD",
        "rate": "11.52945"
      },
      "XAU": {
        "amount": "0.00",
        "balance": "0.00",
        "currency": "USD",
        "rate": "1235.46975"
      },
      "XRP": {
        "amount": "0.00",
        "balance": "0.00",
        "currency": "USD",
        "rate": "0.80000"
      }
    },
    "total": "114611.50"
  },
  "birthdate": "2000-09-27",
  "country": "US",
  "currencies": [
    "AED",
    "ARS",
    "AUD",
    "BAT",
    "BCH",
    "BRL",
    "BTC",
    "BTG",
    "CAD",
    "CHF",
    "CNY",
    "DASH",
    "DKK",
    "ETH",
    "EUR",
    "GBP",
    "HKD",
    "ILS",
    "INR",
    "JPY",
    "KES",
    "LTC",
    "MXN",
    "NOK",
    "NZD",
    "PHP",
    "PLN",
    "SEK",
    "SGD",
    "USD",
    "VOX",
    "XAG",
    "XAU",
    "XPD",
    "XPT",
    "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",
  "username": "malikakoss",
  "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 has become a verified member.

User Settings

User Status

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

When users are in a specific state, the verifications field can help communicate the reasons for account status and potential suspension. 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
birthdate required n/a Whether the user needs to provide his/her date of birth.
email unconfirmed n/a Whether the user needs to confirm his/her email.
identity required, retry, review, running n/a The status of identity verification during membership application process.
location required, blocked country, state Whether the user has specified his/her location, which can be a blocked country/state.
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.

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

curl https://api.uphold.com/v0/me/accounts \
  -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

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.

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

curl https://api.uphold.com/v0/me/cards \
  -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

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
label The display name of the card. Max length: 140 characters.
currency The currency to denominate value stored by the card, represented as a three character currency code.

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 An object with the card’s position and whether it is starred.

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, ethereum or litecoin.

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",
        "username": "angelrath"
      }
    },
    "rate": "0.85620",
    "type": "card",
    "username": "angelrath"
  },
  "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",
        "username": "angelrath"
      }
    },
    "rate": "1.16795",
    "sources": [{
      "amount": "6.56",
      "id": "3db4ef24-c529-421f-8e8f-eb9da1b9a582"
    }],
    "type": "card",
    "username": "angelrath"
  },
  "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

In step one, one prepares the transaction by specifying:

The following table describes the types of transactions currently supported:

Type Origin Destination
deposit ACH, CARD or SEPA account id Uphold card id
withdrawal Uphold card id ACH, SEPA or Bitcoin address
transfer Uphold card id An email address, an application id, an Uphold username or an Uphold card id

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

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.

Request

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

Response

Returns a Transaction Object.

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",
        "username": "angelrath"
      }
    },
    "rate": "0.85620",
    "type": "card",
    "username": "angelrath"
  },
  "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",
        "username": "angelrath"
      }
    },
    "rate": "1.16795",
    "sources": [{
      "amount": "6.56",
      "id": "3db4ef24-c529-421f-8e8f-eb9da1b9a582"
    }],
    "type": "card",
    "username": "angelrath"
  },
  "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 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",
        "username": "angelrath"
      }
    },
    "rate": "0.85620",
    "type": "card",
    "username": "angelrath"
  },
  "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",
        "username": "angelrath"
      }
    },
    "rate": "1.16795",
    "sources": [{
      "amount": "6.56",
      "id": "3db4ef24-c529-421f-8e8f-eb9da1b9a582"
    }],
    "type": "card",
    "username": "angelrath"
  },
  "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 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",
    "rate": "1.00",
    "pair": "USDUSD"
  },
  "fees": [{
    "type": "exchange",
    "amount": "0.00",
    "target": "destination",
    "currency": "BTC",
    "percentage": "0.00"
  }],
  "id": "63dc7ccb-0e57-400d-8ea7-7d903753801c",
  "message": null,
  "params": {
    "currency": "USD",
    "margin": "0.00",
    "pair": "BTCUSD",
    "progress": "1",
    "rate": "900.00000",
    "ttl": 7000,
    "type": "transfer"
  },
  "status": "completed",
  "type": "transfer",
  "normalized": [{
    "fee": "0.00",
    "rate": "0.91759",
    "amount": "22.94",
    "currency": "EUR",
    "commission": "0.00"
  }],
  "origin": {
    "amount": "25.00",
    "base": "25.00",
    "CardId": "f4dbc023-61bb-43e9-9ce6-7f34efd9e688",
    "commission": "0.00",
    "currency": "USD",
    "description": "Nuno Sousa",
    "fee": "0.00",
    "rate": "900.00000",
    "sources": [{
      "id": "4586e3f6-5fff-473f-b479-4e7ce2ba14cf",
      "amount": "25.00"
    }],
    "type": "card",
    "username": "johndoe"
  },
  "destination": {
    "amount": "0.02777777",
    "base": "0.02777777",
    "CardId": "d42999c4-30c9-4a61-889c-62a4050bce88",
    "commission": "0.00",
    "currency": "BTC",
    "description": "Nuno Sousa",
    "fee": "0.00",
    "rate": "0.00111111",
    "type": "card",
    "username": "johndoe"
  }
},
{
  "createdAt": "2016-01-19T12:07:01.611Z",
  "denomination": {
    "amount": "0.01",
    "currency": "BTC",
    "rate": "1.00",
    "pair": "BTCBTC"
  },
  "fees": [{
    "type": "network",
    "amount": "0.0002",
    "target": "origin",
    "currency": "BTC"
  }, {
    "type": "withdrawal",
    "amount": "0.00",
    "target": "origin",
    "currency": "BTC",
    "percentage": "0.5"
  }],
  "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"
  }],
  "params": {
    "currency": "BTC",
    "margin": "0.00",
    "pair": "BTCBTC",
    "progress": "1",
    "rate": "1.00",
    "ttl": 7000,
    "type": "external/out"
  },
  "status": "completed",
  "type": "withdrawal",
  "origin": {
    "amount": "0.0102",
    "base": "0.01",
    "CardId": "d42999c4-30c9-4a61-889c-62a4050bce88",
    "commission": "0.00",
    "currency": "BTC",
    "description": "Nuno Sousa",
    "fee": "0.0002",
    "rate": "1.00",
    "sources": [{
      "id": "390ed0ab-c014-43f3-868a-8ea3ea56025e",
      "amount": "0.0102"
    }],
    "type": "card",
    "username": "johndoe"
  },
  "destination": {
    "address": "n2eMqTT929pb1RDNuqEnxdaLau1rxy3efi",
    "amount": "0.01",
    "base": "0.01",
    "commission": "0.00",
    "currency": "BTC",
    "description": "n2eMqTT929pb1RDNuqEnxdaLau1rxy3efi",
    "fee": "0.00",
    "rate": "1.00",
    "type": "external"
  }
}]

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",
    "rate": "1.00",
    "pair": "USDUSD"
  },
  "fees": [],
  "id": "a97bb994-6e24-4a89-b653-e0a6d0bcf634",
  "params": {
    "currency": "USD",
    "margin": "0.00",
    "pair": "USDUSD",
    "rate": "1.00"
  },
  "status": "cancelled",
  "type": "transfer",
  "origin": {
    "amount": "1.00",
    "base": "1.00",
    "commission": "0.00",
    "currency": "USD",
    "fee": "0.00",
    "rate": "1.00",
    "sources": [{
      "id": "35325c99-edeb-4625-9cd8-f56d4783c352",
      "amount": "1"
    }]
  },
  "destination": {
    "amount": "1.00",
    "base": "1.00",
    "commission": "0.00",
    "currency": "USD",
    "fee": "0.00",
    "rate": "1.00"
  }
}

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.

Contacts

List Contacts

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

The above command returns the following JSON:

[{
  "id": "9fae84eb-712d-4b6a-9b2c-764bdde4c079",
  "firstName": "Han",
  "lastName": "Solo",
  "company": "Rebel Alliance",
  "emails": [
    "[email protected]"
  ],
  "addresses": [],
  "name": "Han Solo"
}, {
  "id": "2f3b26bf-4621-4fe9-ab7d-565105b22588",
  "firstName": "Leia",
  "lastName": "Organa",
  "company": "Galactic Senate",
  "emails": [
    "[email protected]"
  ],
  "addresses": [],
  "name": "Leia Organa"
}]

Request

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

Response

Returns an array of contact objects associated with the current user.

Get Contact

curl https://api.uphold.com/v0/me/contacts/9fae84eb-712d-4b6a-9b2c-764bdde4c079 \
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

{
  "id": "9fae84eb-712d-4b6a-9b2c-764bdde4c079",
  "firstName": "Han",
  "lastName": "Solo",
  "company": "Rebel Alliance",
  "emails": [
    "[email protected]"
  ],
  "addresses": [],
  "name": "Han Solo"
}

Request

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

Response

Returns an associative array containing the details of the designated contact.

Create Contact

curl https://api.uphold.com/v0/me/contacts \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "firstName": "Luke", "lastName": "Skywalker", "company": "Lars Moisture Farm, Inc.", "emails": ["[email protected]"] }'

Request

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

Parameter Description
firstName Contact’s first name. (max: 255 chars)
lastName Contact’s last name. (max: 255 chars)
company Contact’s company. (max: 255 chars)
emails List of email addresses.
addresses List of bitcoin addresses.

Response

A fully formed Contact Object

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"
  },
  "birthdate": "2014-08-27",
  "country": "US",
  "currencies": [
    "BTC"
  ],
  "email": "[email protected]",
  "firstName": "Luke",
  "lastName": "Skywalker",
  "name": "Luke Skywalker",
  "settings": {
    "currency": "USD",
    "intl": {
      "dateTimeFormat": {
        "locale": "en-US"
      },
      "language": {
        "locale": "en-US"
      },
      "numberFormat": {
        "locale": "en-US"
      }
    },
    "otp": {
      "login": {
        "enabled": true
      },
      "transactions": {
        "transfer": {
          "enabled": false
        },
        "send": {
          "enabled": true
        },
        "withdraw": {
          "crypto": {
            "enabled": true
          }
        }
      }
    },
    "theme": "vintage"
  },
  "memberAt": "2015-07-10T15:36:20.288Z",
  "state": "WA",
  "status": "ok",
  "username": "skywalker",
  "verifications": {},
  "balances": {
    "total": "90.00",
    "currencies": {
      "BTC": {
        "amount": "90.00",
        "balance": "0.1",
        "currency": "USD",
        "rate": "900.00000"
      }
    }
  }
}

Request

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

Response

Returns the details associated the current user.

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:

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

Request

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

Response

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

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.

Reserve Status

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

Which returns the following:

[{
  "currency": "BTC",
  "values": [{
    "assets": "287.24725",
    "currency": "BTC",
    "liabilities": "133.789096",
    "rate": "1.00"
  }, {
    "assets": "592404.25",
    "currency": "CNY",
    "liabilities": "275919.87",
    "rate": "2062.34967"
  }, {
    "assets": "76787.16",
    "currency": "EUR",
    "liabilities": "35764.61",
    "rate": "267.31889"
  }, {
    "assets": "60512.35",
    "currency": "GBP",
    "liabilities": "28184.40",
    "rate": "210.66168"
  }, {
    "assets": "10591340.78",
    "currency": "JPY",
    "liabilities": "4933052.69",
    "rate": "36871.86292"
  }, {
    "assets": "96843.97",
    "currency": "USD",
    "liabilities": "45106.32",
    "rate": "337.14500"
  }],
  "totals": {
    "amount": "1755.86701",
    "count": "1136206",
    "assets": "493.75857302",
    "liabilities": "335.82190088"
  }
}, {
  "currency": "CNY",
  "values": [{
    "assets": "0.00",
    "currency": "BTC",
    "liabilities": "1.02929007",
    "rate": "0.00048486"
  }, {
    "assets": "0.00",
    "currency": "CNY",
    "liabilities": "2122.73",
    "rate": "1.00"
  }, {
    "assets": "0.00",
    "currency": "EUR",
    "liabilities": "275.15",
    "rate": "0.12962"
  }, {
    "assets": "0.00",
    "currency": "GBP",
    "liabilities": "216.83",
    "rate": "0.10214"
  }, {
    "assets": "0.00",
    "currency": "JPY",
    "liabilities": "37939.77",
    "rate": "17.87310"
  }, {
    "assets": "0.00",
    "currency": "USD",
    "liabilities": "347.02",
    "rate": "0.16347"
  }],
  "totals": {
    "amount": "3823508.63",
    "count": "1136206",
    "assets": "1018302.81",
    "liabilities": "692583.22"
  }
}, {
  "currency": "EUR",
  "values": [{
    "assets": "0.00",
    "currency": "BTC",
    "liabilities": "12.99977754",
    "rate": "0.00374082"
  }, {
    "assets": "0.00",
    "currency": "CNY",
    "liabilities": "26809.95",
    "rate": "7.71485"
  }, {
    "assets": "0.00",
    "currency": "EUR",
    "liabilities": "3475.11",
    "rate": "1.00"
  }, {
    "assets": "0.00",
    "currency": "GBP",
    "liabilities": "2738.56",
    "rate": "0.78805"
  }, {
    "assets": "0.00",
    "currency": "JPY",
    "liabilities": "479323.83",
    "rate": "137.93055"
  }, {
    "assets": "0.00",
    "currency": "USD",
    "liabilities": "4382.81",
    "rate": "1.26120"
  }],
  "totals": {
    "amount": "491498.28",
    "count": "1136206",
    "assets": "131991.93",
    "liabilities": "89772.20"
  }
}, {
  "currency": "GBP",
  "values": [{
    "assets": "0.00",
    "currency": "BTC",
    "liabilities": "6.66475849",
    "rate": "0.00474691"
  }, {
    "assets": "0.00",
    "currency": "CNY",
    "liabilities": "13745.15",
    "rate": "9.78985"
  }, {
    "assets": "0.00",
    "currency": "EUR",
    "liabilities": "1781.64",
    "rate": "1.26895"
  }, {
    "assets": "0.00",
    "currency": "GBP",
    "liabilities": "1404.02",
    "rate": "1.00"
  }, {
    "assets": "0.00",
    "currency": "JPY",
    "liabilities": "245743.23",
    "rate": "175.02830"
  }, {
    "assets": "0.00",
    "currency": "USD",
    "liabilities": "2246.99",
    "rate": "1.60040"
  }],
  "totals": {
    "amount": "387091.81",
    "count": "1136206",
    "assets": "104016.64",
    "liabilities": "70745.21"
  }
}, {
  "currency": "JPY",
  "values": [{
    "assets": "0.00",
    "currency": "BTC",
    "liabilities": "1.78214122",
    "rate": "0.0000271"
  }, {
    "assets": "0.00",
    "currency": "CNY",
    "liabilities": "3676.53",
    "rate": "0.05595"
  }, {
    "assets": "0.00",
    "currency": "EUR",
    "liabilities": "476.41",
    "rate": "0.00725"
  }, {
    "assets": "0.00",
    "currency": "GBP",
    "liabilities": "375.43",
    "rate": "0.00571"
  }, {
    "assets": "0.00",
    "currency": "JPY",
    "liabilities": "65710.91",
    "rate": "1.00"
  }, {
    "assets": "0.00",
    "currency": "USD",
    "liabilities": "600.84",
    "rate": "0.00914"
  }],
  "totals": {
    "amount": "67366825.69",
    "count": "1136206",
    "assets": "18205797.97",
    "liabilities": "12382365.53"
  }
}, {
  "currency": "USD",
  "values": [{
    "assets": "206.51132302",
    "currency": "BTC",
    "liabilities": "179.55683756",
    "rate": "0.00296608"
  }, {
    "assets": "425898.56",
    "currency": "CNY",
    "liabilities": "370308.99",
    "rate": "6.11710"
  }, {
    "assets": "55204.77",
    "currency": "EUR",
    "liabilities": "47999.28",
    "rate": "0.79289"
  }, {
    "assets": "43504.29",
    "currency": "GBP",
    "liabilities": "37825.97",
    "rate": "0.62484"
  }, {
    "assets": "7614457.19",
    "currency": "JPY",
    "liabilities": "6620595.10",
    "rate": "109.36500"
  }, {
    "assets": "69624.26",
    "currency": "USD",
    "liabilities": "60536.69",
    "rate": "1.00"
  }],
  "totals": {
    "amount": "622844.43",
    "count": "1136206",
    "assets": "166468.23",
    "liabilities": "113220.67"
  }
}]

To assist developers with tracking the overall status of our Reserve, we provide a summary of all the obligations and assets within it. Then for convenience’s sake we compute the value of each our holdings in all of the currencies we support, making it easy for example to display our total US dollar liabilities, but expressed in Euros. For example, a request to fetch a summary will return an array of assets with the following properties:

Property Description
currency The asset class of the holding being summarized.
values Expresses the value of held in the associated currency in all supported forms.
totals Lists the commissions, transaction volume, assets and liabilities.

Each normalized holding has the following properties:

Property Description
assets The quantity of assets held for the corresponding holding, but converted to a different currency.
liabilities The quantity of liabilities for the corresponding holding, but converted to a different currency.
currency The currency we are computing the current holding in.
rate The rate we used when computing the holding to the corresponding currency.

Request

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

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.

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

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.

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

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:

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

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.

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

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.

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

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

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

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.

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

Transfers

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

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

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 Range & Content-Range entity-headers.

Request

You can provide the Range header specifying how many items you want to retrieve.

Here is an example:

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

The above command will return the user’s last five transactions.

Response

The endpoints that support pagination returns a Content-Range header. For instance, if you make a request with Range: items=0-4 header the response will contain the following header: Content-Range: 0-4/* where * will be the total number of items that this endpoint can return.

If the Range header is malformed or if the range cannot be satisfied you will receive a 412 error or a 416 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 300 / 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 /oauth2/token 10 / 1-min window 10 / 1-min window
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-Total The total number of requests possible in the current window duration
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
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-Total: 300
Rate-Limit-Remaining: 299
Rate-Limit-Reset: 1422288284

When the API limit is reached, a status code of 429 Too Many Requests is returned with the aforementioned Retry-After header:

Example response for a rate limited request:

HTTP/1.1 429 Too Many Requests

Rate-Limit-Total: 300
Rate-Limit-Remaining: 0
Rate-Limit-Reset: 1422288284
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 – Validation failed.
401 Unauthorized – Bad credentials.
403 Forbidden – Access forbidden.
404 Not Found – Object not found.
409 Conflict – Entity already exists.
412 Precondition Failed
416 Requested Range Not Satisfiable
429 Too Many Requests – Rate limit exceeded.
500 Internal Server Error – Something went wrong in our server.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again in a little bit.

Support

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