API Reference
These docs are for v3. Click to read the latest docs for v4.

Wallets

Overview

Wallets are used to hold cryptocurrency funds on the Wyre platform. White-label wallets are spun up on demand via the Create Wallet endpoint.

Wallets are able to hold cryptocurrency and fiat balances for Supported Currencies and support transfers and exchanges.

Creating a Wallet

The Create Wallet endpoint has a name parameter which allows you to attach a unique identifier to the wallet, perhaps a user id generated by your app/platform.

The type parameter allows you to choose the type of wallet to create from the following options:

  • DEFAULT
  • ENTERPRISE
  • SAVINGS

Wallets are attached to your Wyre business account at the platform level and allow you to operate them on behalf of your users via the Transfers endpoint.

Building the Create Wallet Request

When building your request to create a new wallet, you'll need to provide these fields:

  • name - Your unique identifier for this user.
  • callbackUrl - Optional callback when the user receives funds (payload)
  • notes - Optional notes about the user
  • type - The type of user you are creating, DEFAULT, ENTERPRISE or SAVINGS. When creating a wallet for SAVINGS, please follow the Wyre+ Rewards Wallets Guide.

Response

When a new wallet is created you will receive the following:

  • name - Your identifier
  • id - Wyre's identifier
  • depositAddresses - Digital currency deposit addresses for the user
  • totalBalances - Total balance for the user
  • availableBalances - Funds available to the user
  • pusherChannel - Pusher update channel
  • srn - Wyre Reference Name identifier
  • balances - Balances for the user
  • callbackUrl - Your callback url
  • notes - Your note for the user
  • verificationData - KYC information for the user

Transferring Between Wallets

The Transfers endpoint facilitates movement of cryptocurrency between Wyre wallets and crypto wallets external to Wyre.

📘

Transfers and SRNs

In this example, a user creates a transfer from their Wyre wallet to another Wyre wallet on the same platform. The specific wallet is determined by the selected destination currency i.e. "BTC" will deliver Bitcoin to the destination wallet's Bitcoin address. Notice the wallet: prefix concatenated to the wallet id. These SRN prefixes are necessary.

"source":"wallet:WA_XXXXXXXX1",
"dest":"wallet:WA_XXXXXXXX2",

A user could also create a transfer from their Wyre wallet to another external crypto wallet, like below. Notice the bitcoin: prefix concatenated to the Bitcoin address. These SRN prefixes are necessary.

"source":"wallet:WA_XXXXXXXX2",
"dest":"bitcoin:1DDfMQLTd8RhGzoyWyr1ENVdoeGaoq2MZH",

To see the full list of required parameters for a transfer click here.

Wallet Callbacks

We provide a series of HTTP callbacks that allow you to notify users when funds have been deposited and when they become available. When creating a wallet, you can set a callbackUrl. The following information describes the structure of the callbacks received.

When callbacks are sent

Callbacks are sent whenever a transactional event occurs that will affect the wallet's balance. Examples include:

  • Incoming pending transaction
  • Pending transaction confirmed
  • Outgoing transaction
    You may receive two callbacks for a single transaction. This is especially true for transactions on the blockchain. In these cases, you would receive one callback when the transaction is first observed and one callback once the transaction is confirmed.

Callback Acceptance and Retries

Your system should respond to the callback request with a 200 response. We only attempt to send the request once, but we may introduce automatic retries in the future. We can manually resend callbacks upon request.

Payload

The callback payload will be a JSON representation of the transaction that has caused the callback to trigger. An example of such a transaction can be found below:

//Incoming BTC deposit from external BTC wallet.
{
  "createdAt": 1613027293110,
  "id": "TR_7NVXRFRBZJV",
  "source": "bitcoin:EXTERNAL",
  "dest": "wallet:WA_8AFWHMHLYXH",
  "currency": "BTC",
  "amount": 0.01653538,
  "status": "CONFIRMED",
  "confirmedAt": 1613027293110,
  "cancelledAt": null,
  "reversedAt": null,
  "message": null,
  "allowOverdraft": true,
  "authorizer": null,
  "senderProvidedId": null,
  "reversedBy": null,
  "fees": 0,
  "feesDest": null,
  "metadata": {
    "BTCNetworkTxId": "9689d7c675b05f71629696ea9b25c2d61f52406598a4bef759f782c2c35d4f0c"
  },
  "tags": [],
  "destFees": null,
  "sourceFees": null
}

//Incoming ETH deposit from external ETH wallet.
{
  "createdAt": 1614721011262,
  "id": "TR_V8WQDC27BX8",
  "source": "ethereum:0x003bbce1eac59b406dd0e143e856542df3659075",
  "dest": "wallet:WA_3FE7HZHCYBG",
  "currency": "ETH",
  "amount": 6,
  "status": "CONFIRMED",
  "confirmedAt": 1614721011262,
  "cancelledAt": null,
  "reversedAt": null,
  "message": null,
  "allowOverdraft": true,
  "authorizer": null,
  "senderProvidedId": null,
  "reversedBy": null,
  "fees": 0,
  "feesDest": null,
  "metadata": {
    "ETHNetworkTxId": "0x816091d7fd5fe99b6b9f5cefafe01a39e0c4aca6b44e6d8ee32164b6097ea5d6"
  },
  "tags": [],
  "sourceFees": null,
  "destFees": null
}

// Interest payouts require resolving the transfer id.
// GET https://api.testwyre.com/v3/transfers/TF_HTQEQ327NYE
{
  "createdAt": 1617235219704,
  "id": "TR_AE79Q7L6QAT",
  "source": "transfer:TF_HTQEQ327NYE",
  "dest": "wallet:WA_8TJFJ3EQEN9",
  "currency": "BTC",
  "amount": 0.0000106,
  "status": "CONFIRMED",
  "confirmedAt": 1617235219704,
  "cancelledAt": null,
  "reversedAt": null,
  "message": "Deposit for transfer TF_HTQEQ327NYE",
  "allowOverdraft": true,
  "authorizer": "service:Nobody",
  "senderProvidedId": null,
  "reversedBy": null,
  "fees": 0,
  "feesDest": null,
  "metadata": {
    "transferId": "TF_HTQEQ327NYE"
  },
  "tags": [],
  "sourceFees": null,
  "destFees": null
}

Security Signature

In order to prevent callback spoofing, we provide a signature with the callback passed back through the HTTP header X-API-Signature.

i.e. x-api-signature: 56a00765528a6a6fab70c9272485131f157a423f78a5ab06d2c8627f867f6aea

This signature is a SHA256 HMAC signature of the JSON body signed with the merchant's secret key. To the right you can find example implementations of the signature.

Note: It's important to verify the signature in the callback, otherwise it is possible for the request to be spoofed by an external attacker.

Interest Payouts and Account Sources

Certain types of transfers will display the "source" as a transfer SRN. This requires that you query the transfer id to get the details of the transfer. This is the case for rewards wallets and subsequent interest payouts.

You can determine if a callback is the result of an interest payout by querying the transfer id in the "source," for example:

If a callback presents with a source like this: "source": "transfer:TF_HTQEQ327NYE," you can query the transfer id with GET https://api.testwyre.com/v3/transfers/TF_HTQEQ327NYE. The result will look like the sample below. Notice the source of the transfer: "source": "service:Interest Payments",

{
    "owner": "service:Nobody",
    "status": "COMPLETED",
    "source": "service:Interest Payments",
    "createdAt": 1617235217000,
    "sourceAmount": 0.0000106,
    "destCurrency": "BTC",
    "sourceCurrency": "BTC",
    "totalFees": 0,
    "customId": null,
    "completedAt": 1617235220000,
    "cancelledAt": null,
    "failureReason": null,
    "expiresAt": 1617494417000,
    "updatedAt": 1617235220000,
    "fees": {
        "BTC": 0E-8
    },
    "destAmount": 0.0000106,
    "exchangeRate": null,
    "statusHistories": [
        {
            "id": "BBGZBGDVWUR",
            "transferId": "TF_HTQEQ327NYE",
            "createdAt": 1617235220000,
            "type": "ADMIN_CREDIT",
            "statusOrder": 0,
            "statusDetail": "Initiating Transfer",
            "state": "INITIATED",
            "failedState": null
        },
        {
            "id": "GUMTCX4QUEH",
            "transferId": "TF_HTQEQ327NYE",
            "createdAt": 1617235220000,
            "type": "ADMIN_CREDIT",
            "statusOrder": 5100,
            "statusDetail": "Transfer Completed",
            "state": "COMPLETED",
            "failedState": null
        }
    ],
    "estimatedArrival": 1617847722127,
    "dest": "wallet:WA_8TJFJ3EQEN9",
    "pendingSubStatus": null,
    "blockchainTx": null,
    "reversalReason": null,
    "reversingSubStatus": null,
    "message": null,
    "id": "TF_HTQEQ327NYE"
}