NAV
php shell

XWallet API

Welcome to the XWallet API.

XWallet is a Bitcoin and Counterparty wallet notification API. Private keys are held by the user of this API and not held by the server.

Authentication

All API calls require authentication. See https://github.com/tokenly/hmac-auth/blob/master/README.md for details.

Address Methods

Add a new address

<?php
$api = new XWalletAPI(); # note - The PHP API client doesn't exist just yet
$address = '1YxC7GN6NipW12XLPuCFcTFfkMKYAu1Lb';
$bot_data = $api->newAddress($address);
ADDRESS="1YxC7GN6NipW12XLPuCFcTFfkMKYAu1Lb"
WEBHOOK_ENDPOINT="http://mysite.com/callback"

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "POST\nhttps://xwallet.tokenly.com/api/v1/addresses\n{"address":"$ADDRESS","webhookEndpoint":"$WEBHOOK_ENDPOINT"}\n${API_TOKEN}\n${NONCE}" \
    | openssl dgst -sha256 -hmac "${API_SECRET_KEY}" -binary | base64)

curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-TOKENLY-AUTH-API-TOKEN: ${API_TOKEN}" \
    -H "X-TOKENLY-AUTH-NONCE: ${NONCE}" \
    -H "X-TOKENLY-AUTH-SIGNATURE: ${SIGNATURE}" \
    -d '{"address":"'$ADDRESS'","webhookEndpoint":"'$WEBHOOK_ENDPOINT"}' \
    https://xwallet.tokenly.com/api/v1/addresses

The above command returns data structured like the following. Note that there may be more data returned than listed below.

{
    "address": "1YxC7GN6NipW12XLPuCFcTFfkMKYAu1Lb",
    "id": "8baaaaaa-1234-5678-1234-aaaaaaaa1111",
    "sendMonitorId": "3bcccccc-1234-5678-1234-cccccccc2222",
    "receiveMonitorId": "4bdddddd-1234-5678-1234-dddddddd3333"
}

Add a bitcoin address to be managed by this user.

HTTP Request

POST https://xwallet.tokenly.com/api/v1/addresses

Body Parameters

Parameter Description
address A bitcoin address
webhookEndpoint An optional URL endpoint to post address events (such as send or receive)

Remove an address

<?php
$api = new XWalletAPI(); # note - The PHP API client doesn't exist just yet
$address_uuid = '8ccccccc-1234-5678-1234-cccccccc1111';
$bot_data = $api->destroyAddress($address_uuid);
ADDRESS_UUID="8ccccccc-1234-5678-1234-cccccccc1111"

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "DELETE\nhttps://xwallet.tokenly.com/api/v1/addresses/${ADDRESS_UUID}\n{}\n${API_TOKEN}\n${NONCE}" \
    | openssl dgst -sha256 -hmac "${API_SECRET_KEY}" -binary | base64)

curl -X DELETE \
    -H "X-TOKENLY-AUTH-API-TOKEN: ${API_TOKEN}" \
    -H "X-TOKENLY-AUTH-NONCE: ${NONCE}" \
    -H "X-TOKENLY-AUTH-SIGNATURE: ${SIGNATURE}" \
    https://xwallet.tokenly.com/api/v1/addresses/$ADDRESS_UUID

The above command returns an empty response with HTTP code 204.

Removes a bitcoin address that is managed by this client.

HTTP Request

DELETE https://xwallet.tokenly.com/api/v1/addresses/{addressId}

URL Parameters

Parameter Description
addressId The UUID of the address (not the bitcoin address itself)

Send Methods

Create a new unsigned send transaction

<?php
$api = new XWalletAPI(); # note - The PHP API client doesn't exist just yet
$address_uuid = '8ccccccc-1234-5678-1234-cccccccc1111';
$unsigned_send_data = $api->createNewSend($address_uuid, 3, 'TOKENLY', '1TEST1111xxxxxxxxxxxxxxxxxxxtjomkj');
ADDRESS_UUID="8ccccccc-1234-5678-1234-cccccccc1111"

DESTINATION="1TEST1111xxxxxxxxxxxxxxxxxxxtjomkj"
QUANTITY="3"
ASSET="TOKENLY"

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "POST\nhttps://xwallet.tokenly.com/api/v1/sends/${ADDRESS_UUID}\n{\"destination\":\"$DESTINATION\",\"quantity\":\"$QUANTITY\",\"asset\":\"$ASSET\"}\n${API_TOKEN}\n${NONCE}" \
    | openssl dgst -sha256 -hmac "${API_SECRET_KEY}" -binary | base64)

curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-TOKENLY-AUTH-API-TOKEN: ${API_TOKEN}" \
    -H "X-TOKENLY-AUTH-NONCE: ${NONCE}" \
    -H "X-TOKENLY-AUTH-SIGNATURE: ${SIGNATURE}" \
  -d '{"destination":"'$DESTINATION'","quantity":"'$QUANTITY'","asset":"'$ASSET'"}' \
  https://xwallet.tokenly.com/api/v1/sends/$ADDRESS_UUID

The above command returns data structured like the following. Note that there may be more data returned than listed below.

{
    "id": "8ccccccc-1234-5678-1234-cccccccc1111",
    "destination": "1TEST1111xxxxxxxxxxxxxxxxxxxtjomkj",
    "quantity": 3,
    "asset": "TOKENLY",
    "txid": "a123456789123456789123456789123456789123456789123456789aaabbbccc",
    "unsignedTx": "0000113111deadbeef0000aaabcdef1111110000113111deadbeef0000aaabcdef1111110000113111deadbeef0000aaabcdef1111110000113111deadbeef0000aaabcdef111111",
    "utxos": [
        {
            "amount": 1000000,
            "n": 0,
            "script": "feeb0000aaabcdef11111100feeb0000aaabcdef11111100aa",
            "txid": "a123bbbbbbbbcccccccc3456789123456789123456789123456789aaabbbccc"
        }
    ]
}

Creates a new, unsigned transaction. XWallet will not allow any further transaction creation for this address until you either submit or destroy this transaction.

UTXOs are provided in order to sign the inputs for this transaction. UTXO amounts are in satoshis.

HTTP Request

POST https://xwallet.tokenly.com/api/v1/sends/{addressId}

URL Parameters

Parameter Description
addressId The UUID of the address to send from. This is not the bitcoin address.

Body Parameters

Parameter Description
destination The destination bitcoin address
quantity Quantity to send as a float
asset The token to send such as BTC or TOKENLY
fee The BTC fee to pay as a float (optional)
unconfirmed If true, then spend unconfirmed inputs (optional)

Submits a signed send transaction to the bitcoin network

<?php
$api = new XWalletAPI(); # note - The PHP API client doesn't exist just yet
$send_uuid = '8ccccccc-1234-5678-1234-cccccccc1111';
$signed_transaction_hex = '0000113111deadbeef0000aaabcdef1111110000113111deadbeef';
$sent_data = $api->submitSend($send_uuid, $signed_transaction_hex);
SEND_UUID="8ccccccc-1234-5678-1234-cccccccc1111"
SIGNED_TX_HEX="0000113111deadbeef0000aaabcdef1111110000113111deadbeef"

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "POST\nhttps://xwallet.tokenly.com/api/v1/signed/sends/${SEND_UUID}\n{\"signedTx\":\"$SIGNED_TX_HEX\"}\n${API_TOKEN}\n${NONCE}" \
    | openssl dgst -sha256 -hmac "${API_SECRET_KEY}" -binary | base64)

curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-TOKENLY-AUTH-API-TOKEN: ${API_TOKEN}" \
    -H "X-TOKENLY-AUTH-NONCE: ${NONCE}" \
    -H "X-TOKENLY-AUTH-SIGNATURE: ${SIGNATURE}" \
  -d '{"signedTx":"'$SIGNED_TX_HEX'"}' \
  https://xwallet.tokenly.com/api/v1/signed/sends/$SEND_UUID

The above command returns data structured like the following. Note that there may be more data returned than listed below.

{
    "txid": "a123456789123456789123456789123456789123456789123456789aaabbbccc"
}

Broadcasts the send to the bitcoin network and unlocks the pending send.

HTTP Request

POST https://xwallet.tokenly.com/api/v1/signed/sends/{sendId}

URL Parameters

Parameter Description
sendId The UUID of the Send Transaction

Body Parameters

Parameter Description
signedTx The signed transaction, encoded as a hexadecimal string

Delete an unsigned send transaction

<?php
$api = new XWalletAPI(); # note - The PHP API client doesn't exist just yet
$send_uuid = '8ccccccc-1234-5678-1234-cccccccc1111';
$bot_data = $api->destroySend($send_uuid);
SEND_UUID="8ccccccc-1234-5678-1234-cccccccc1111"

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "DELETE\nhttps://xwallet.tokenly.com/api/v1/sends/${SEND_UUID}\n{}\n${API_TOKEN}\n${NONCE}" \
    | openssl dgst -sha256 -hmac "${API_SECRET_KEY}" -binary | base64)

curl -X DELETE \
    -H "X-TOKENLY-AUTH-API-TOKEN: ${API_TOKEN}" \
    -H "X-TOKENLY-AUTH-NONCE: ${NONCE}" \
    -H "X-TOKENLY-AUTH-SIGNATURE: ${SIGNATURE}" \
    https://xwallet.tokenly.com/api/v1/sends/$SEND_UUID

The above command returns an empty response with HTTP code 204.

Destroys a pending unsigned send. This will release any UTXOs marked as spent by XWallet.

HTTP Request

DELETE https://xwallet.tokenly.com/api/v1/sends/{sendId}

URL Parameters

Parameter Description
sendId The UUID of the Send Transaction

Address Balance Methods

Get balances for an address

<?php
$api = new XWalletAPI(); # note - The PHP API client doesn't exist just yet
$address_uuid = '8ccccccc-1234-5678-1234-cccccccc1111';
$bot_data = $api->getBalances($address_uuid);
ADDRESS_UUID="8ccccccc-1234-5678-1234-cccccccc1111"

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "GET\nhttps://xwallet.tokenly.com/api/v1/balances/${ADDRESS_UUID}\n{}\n${API_TOKEN}\n${NONCE}" \
    | openssl dgst -sha256 -hmac "${API_SECRET_KEY}" -binary | base64)

curl -X GET \
    -H "X-TOKENLY-AUTH-API-TOKEN: ${API_TOKEN}" \
    -H "X-TOKENLY-AUTH-NONCE: ${NONCE}" \
    -H "X-TOKENLY-AUTH-SIGNATURE: ${SIGNATURE}" \
    https://xwallet.tokenly.com/api/v1/balances/$ADDRESS_UUID

The above command returns data structured like the following. Note that there may be more data returned than listed below.

{
    "id": "8ccccccc-1234-5678-1234-cccccccc1111",
    "active": true,
    "balances": {
        "unconfirmed": {
            "BTC": 0.05
        },
        "confirmed": {
            "BTC": 0.12,
            "TOKENLY": 10
        },
        "sending": {
            "TOKENLY": 2
        }
    }
}

Returns an array of balances for this address. Balances are considered unconfirmed until 2 confirmations are received. Sent balances are immediately deducted from the confirmed amount and are reported as sending for 2 confirmations.

HTTP Request

GET https://xwallet.tokenly.com/api/v1/balances/{addressId}

URL Parameters

Parameter Description
addressId The UUID of the address to send from. This is not the bitcoin address.

Token Information Methods

Get token meta information

<?php
$api = new XWalletAPI(); # note - The PHP API client doesn't exist just yet
$asset_name = 'TOKENLY';
$asset_info = $api->getTokenMeta($asset_name);
TOKEN_NAME="TOKENLY"

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "GET\nhttps://xwallet.tokenly.com/api/v1/assets/${TOKEN_NAME}\n{}\n${API_TOKEN}\n${NONCE}" \
    | openssl dgst -sha256 -hmac "${API_SECRET_KEY}" -binary | base64)

curl -X GET \
    -H "X-TOKENLY-AUTH-API-TOKEN: ${API_TOKEN}" \
    -H "X-TOKENLY-AUTH-NONCE: ${NONCE}" \
    -H "X-TOKENLY-AUTH-SIGNATURE: ${SIGNATURE}" \
    https://xwallet.tokenly.com/api/v1/assets/$TOKEN_NAME

The above command returns data structured like the following. Note that there may be more data returned than listed below.

{
    "asset": "TOKENLY",
    "description": "Tokenly.co",
    "divisible": true,
    "issuer": "12717MBviQxttaBVhFGRP1LxD8X6CaW452",
    "locked": false,
    "owner": "12717MBviQxttaBVhFGRP1LxD8X6CaW452",
    "supply": 10000000000000
}

Returns the asset information for the given token.

HTTP Request

GET https://xwallet.tokenly.com/api/v1/assets/{tokenName}

URL Parameters

Parameter Description
tokenName The UUID of the address to send from. This is not the bitcoin address.

Errors

The XWallet API uses the following error codes:

Error Code Name Meaning
403 Forbidden The credentials are wrong or missing
404 Not Found The resource is not found
405 Method Not Allowed You tried to access an endpoint with an invalid method
410 Gone The requested resource is no longer present
429 Too Many Requests Too Many Requests
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We’re temporarially offline for maintenance. Please try again later.