NAV
shell php

Token Delivery Service API

Welcome to the Token Delivery Service API.

All API calls begin with https://deliver.tokenly.com.

Email team@tokenly.com for API access

Authentication

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

Source Address Methods

A ‘source address’ is a multi-sig bitcoin address which holds the 'inventory’ for your deliveries.

You may only send token deliveries from a source address up to it’s current real token balance, ensuring a 100% reserve for outgoing payments.

Request a new source address

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "POST\nhttps://deliver.tokenly.com/api/v1/source\n{\"type\": \"2:2\", \"label\": \"Game Fountain\", \"callback_url\": \"http://myapp.com/joinedhook\", \"webhook\": \"http://myapp.com/transactionhook\"}\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 '{"type": "2:2", "label": "Game Fountain", "callback_url": "http://myapp.com/joinedhook", "webhook": "http://myapp.com/transactionhook"}' \
    https://deliver.tokenly.com/api/v1/source
<?php

$client = new Tokenly\DeliveryClient\Client('https://deliver.tokenly.com', $API_TOKEN, $API_SECRET_KEY);

$label         = "Game Fountain";
$type          = "2:2";
$webhook       = "http://myapp.com/transactionhook";
$join_callback = "http://myapp.com/joinedhook";

$response = $client->newSourceAddress($label, $type, $webhook, $join_callback);

The above command returns data structured like this:

{
    "id": "1ce9fa7a-5b86-4a88-8aa9-8a17105ad49a",
    "joinCode": "Fenq762M2AHEBYUbnZGUweKxRocmqszNNZwzAWnj3ETR9Up3ThUPJqQ5vBq3f7eA2RL7obxoC6L",
    "joinCallback": "http://my-app.com/joinedhook",
    "webhook": "http://my-app.com/transactionhook",
    "address": null,
    "complete": false,
    "label": "Game Fountain",
    "type": "2:2",
    "autoFulfill": true,
    "active": true,
    "createdAt": "2016-10-21T14:57:37+0000",
    "updatedAt": "2016-10-21T14:57:37+0000"
}

When a new source address is requested, a join_code is provided which you (the client) can enter in to your Tokenly Pockets wallet to join as a shared wallet cosigner. If using type='2:2', all deliveries must be manually approved via the wallet. If using 2 of 3 types or greater, full automation can be achived via automated cosigner agents which validate, accept and sign transaction proposals.

HTTP Request

POST https://deliver.tokenly.com/api/v1/source

Body Parameters

Parameter Description
type (string, Optional) Either 2:2 or 2:3. Default is 2:3
label (string, Optional) label for reference purposes
join_callback (string, Optional) callback URL if using the join_code method. Notifies the desired endpoint of the generated address when the wallet is joined
webhook (string, Optional) webhook URL to notify of sends and receives related to this address. This overrides the API user level default_webhook
auto_fulfil (boolean, Optional) Causes deliveries from this source address to be marked ready and fulfilled automatically when delivery_date is triggered. Default is true.
active (boolean, Optional) Start this source address off as active or inactive (stops processing deliveries)
desired_utxo_primes (integer, Optional) Choose how many spare UTXOs you want to keep to facilitate smooth transactions

Get source address details

SOURCE_ADDRESS_UUID="8ccccccc-1234-5678-1234-cccccccc1111"

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "GET\nhttps://deliver.tokenly.com/api/v1/source/${SOURCE_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://deliver.tokenly.com/api/v1/source/$SOURCE_ADDRESS_UUID
<?php

$client = new Tokenly\DeliveryClient\Client('https://deliver.tokenly.com', $API_TOKEN, $API_SECRET_KEY);

$uuid = "b1817e08-6537-4685-8435-ca9987d927f8";

$response = $client->getSourceAddress($uuid);

The above command returns data structured like the following:

{
    "id": "b1817e08-6537-4685-8435-ca9987d927f8",
    "joinCode": "Fenq762M2AHEBYUbnZGUweKxRocmqszNNZwzAWnj3ETR9Up3ThUPJqQ5vBq3f7eA2RL7obxoC6L",
    "joinCallback": "http://my-app.com/joinedhook",
    "complete": false,
    "label": "Game Fountain",
    "type": "2:2",
    "webhook": "http://my-app.com/transactionhook",
    "address": "3AAAA1111xxxxxxxxxxxxxxxxxxy43CZ9j",
    "autoFulfill": false,
    "active": true,
    "createdAt": "2016-10-21T15:38:36+0000",
    "updatedAt": "2016-10-21T15:38:36+0000",
    "desiredUtxoPrimes": 12,
    "balances": [],
    "availableBalances": [],
    "unconfirmedBalances": [],
    "pendingDeliveries": []
}

Returns the details for this address. Includes current balances and pending delivery balances. unconfirmedBalances includes pending transactions with 0 or 1 confirmations. Pending transactions over 4 days old are not included in the unconfirmed balances.

HTTP Request

GET https://deliver.tokenly.com/api/v1/source/{addressId}

URL Parameters

Parameter Description
addressId The UUID of the source address. This is not the bitcoin address.

Get a list of source addresses

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "GET\nhttps://deliver.tokenly.com/api/v1/source\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://deliver.tokenly.com/api/v1/source
<?php

$client = new Tokenly\DeliveryClient\Client('https://deliver.tokenly.com', $API_TOKEN, $API_SECRET_KEY);

$response = $client->getSourceAddressList();

The above command returns data structured like the following:

{
    "count": 2,
    "items": [
        {
            "id": "b1817e08-6537-4685-8435-ca9987d927f8",
            "joinCode": "Fenq762M2AHEBYUbnZGUweKxRocmqszNNZwzAWnj3ETR9Up3ThUPJqQ5vBq3f7eA2RL7obxoC6L",
            "joinCallback": "http://my-app.com/joinedhook",
            "complete": false,
            "label": "Game Fountain",
            "type": "2:2",
            "webhook": "http://my-app.com/transactionhook",
            "address": "3AAAA1111xxxxxxxxxxxxxxxxxxy43CZ9j",
            "autoFulfill": false,
            "active": true,
            "createdAt": "2016-10-21T15:38:36+0000",
            "updatedAt": "2016-10-21T15:38:36+0000",
            "desiredUtxoPrimes": 12
        },
        {
            "id": "10a0fd56-3b14-4de0-9f11-dbdd8fd8721c",
            "joinCode": "Fabc123456789012aMTHjrXkEbpzdfmAAMjmNJaw3RGE9Hc3GuHCWdD5iOd3s7rN2EY7bokbP6Y",
            "joinCallback": "http://my-app.com/joinedhook2",
            "complete": false,
            "label": "Other Source",
            "type": "2:2",
            "webhook": "http://my-app.com/transactionhook2",
            "address": "3AAAA1111xxxxxxxxxxxxxxxxxxy43CZ9j",
            "autoFulfill": true,
            "active": true,
            "createdAt": "2016-10-21T15:38:36+0000",
            "updatedAt": "2016-10-21T15:38:36+0000",
            "desiredUtxoPrimes": 12
        }
    ]
}

Returns a list of all source addresses owned by the authenticated user.

HTTP Request

GET https://deliver.tokenly.com/api/v1/source

Update an existing source address

SOURCE_ADDRESS_UUID="8ccccccc-1234-5678-1234-cccccccc1111"

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "PATCH\nhttps://deliver.tokenly.com/api/v1/source/${SOURCE_ADDRESS_UUID}\n{\"label\": \"Game River\", \"join_callback\": \"http://my-app.com/updated-joined-hook\"}\n${API_TOKEN}\n${NONCE}" \
    | openssl dgst -sha256 -hmac "${API_SECRET_KEY}" -binary | base64)

curl -X PATCH \
    -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 '{"label": "Game River", "join_callback": "http://my-app.com/updated-joined-hook"}' \
    https://deliver.tokenly.com/api/v1/source/$SOURCE_ADDRESS_UUID
<?php

$client = new Tokenly\DeliveryClient\Client('https://deliver.tokenly.com', $API_TOKEN, $API_SECRET_KEY);

$uuid = "1ce9fa7a-5b86-4a88-8aa9-8a17105ad49a";
$data = [
    'label'         => 'Game River',
    'join_callback' => 'http://my-app.com/updated-joined-hook',
];

$response = $client->updateSourceAddress($uuid, $data);

The above command returns data structured like this:

{
    "id": "1ce9fa7a-5b86-4a88-8aa9-8a17105ad49a",
    "joinCode": "Fenq762M2AHEBYUbnZGUweKxRocmqszNNZwzAWnj3ETR9Up3ThUPJqQ5vBq3f7eA2RL7obxoC6L",
    "joinCallback": "http://my-app.com/updated-joined-hook",
    "webhook": "http://my-app.com/transactionhook",
    "address": "3AAAA1111xxxxxxxxxxxxxxxxxxy43CZ9j",
    "complete": false,
    "label": "Game River",
    "type": "2:2",
    "autoFulfill": true,
    "active": true,
    "createdAt": "2016-10-21T14:57:37+0000",
    "updatedAt": "2016-10-21T14:57:37+0000",
    "desiredUtxoPrimes": 12,
    "balances": [],
    "availableBalances": [],
    "unconfirmedBalances": [],
    "pendingDeliveries": []
}

Update an existing source address. Some fields are allowed to be changed.

HTTP Request

PATCH https://deliver.tokenly.com/api/v1/source/{addressId}

URL Parameters

Parameter Description
addressId The UUID of the source address. This is not the bitcoin address.

Body Parameters

Parameter Description
label (string, Optional) label for reference purposes
join_callback (string, Optional) callback URL if using the join_code method. Notifies the desired endpoint of the generated address when the wallet is joined
webhook (string, Optional) webhook URL to notify of sends and receives related to this address. This overrides the API user level default_webhook
auto_fulfill (boolean, Optional) Causes deliveries from this source address to be marked ready and fulfilled automatically when delivery_date is triggered. Default is true.
active (boolean, Optional) Change the active status of this address
desired_utxo_primes (integer, Optional) Choose how many spare UTXOs you want to keep to facilitate smooth transactions

Delete a source address

SOURCE_ADDRESS_UUID="8ccccccc-1234-5678-1234-cccccccc1111"

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

curl -X DELETE \
    -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 '{"sweep_address": "1AAAA1111xxxxxxxxxxxxxxxxxxy43CZ9j"}' \
    https://deliver.tokenly.com/api/v1/source/$SOURCE_ADDRESS_UUID
<?php

$client = new Tokenly\DeliveryClient\Client('https://deliver.tokenly.com', $API_TOKEN, $API_SECRET_KEY);

$uuid          = "8ccccccc-1234-5678-1234-cccccccc1111";
$sweep_address = '1AAAA1111xxxxxxxxxxxxxxxxxxy43CZ9j';

$response = $client->shutdownSourceAddress($uuid, $sweep_address);

The above command returns data structured like this:

{
    "result": true
}

Shutdown and archive an existing source address. Any pending deliveries tied to this source address must be canceled first or this request will fail. Sweeps all funds to backup_address if provided.

HTTP Request

DELETE https://deliver.tokenly.com/api/v1/source/{addressId}

URL Parameters

Parameter Description
addressId The UUID of the source address. This is not the bitcoin address.

Body Parameters

Parameter Description
sweep_address (string, Optional) An address to send all tokens and BTC. If not provided, the user’s backup address is used.

Token Delivery Methods

A Token Delivery is the automated or semi-automated movement of tokens from a source address to a destination bitcoin address. The source address holds the merchant or service’s inventory and the destination is typically a client or customer.

A delivery happens in two stages. Stage 1 is a Promise and stage 2 is a Fulfillment.

The promise stage happens immediately when registering a new delivery into the system (unless otherwise requested). This allows for any Tokenpass user with the correct verified Bitcoin address to receive the immediate benefits of Token Controlled Access.

Deliveries remain in a promise stage until either manually marked as ready by the client application. If a delivery_date timestamp is set, then the delivery is marked `ready when that time is reached.

Fullfillments can be executed individually or using a mass distribution tool. For individual fulfillments, the single transaction ID is saved and observed for confirmations. When the transaction is confirmed, the delivery is markied complete and the client application is notified.

Multiple address fullfillments of the same token use Bitsplit for automated mass distribution. For fulfillments via Bitsplit, we wait for Bitsplit to inform us when the entire distribution is complete.

Create a Token Delivery

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "POST\nhttps://deliver.tokenly.com/api/v1/delivery\n{\"source\": \"9793f526-d01b-4a48-9569-0a72a3096b06\", \"destination\": \"1AAAA1111xxxxxxxxxxxxxxxxxxy43CZ9j\", \"token\": \"SOUP\", \"quantity\": 500000000, \"deliveryDate\": 1477166400}\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 '{"source": "9793f526-d01b-4a48-9569-0a72a3096b06", "destination": "1AAAA1111xxxxxxxxxxxxxxxxxxy43CZ9j", "token": "SOUP", "quantity": 500000000, "deliveryDate": 1477166400}' \
    https://deliver.tokenly.com/api/v1/delivery
<?php

$client = new Tokenly\DeliveryClient\Client('https://deliver.tokenly.com', $API_TOKEN, $API_SECRET_KEY);

$source      = "9793f526-d01b-4a48-9569-0a72a3096b06";
$destination = "1AAAA1111xxxxxxxxxxxxxxxxxxy43CZ9j";
$token       = "SOUP";
$quantity    = 500000000;

$response = $client->newDelivery($source, $destination, $token, $quantity);

The above command returns data structured like this:

{
    "id": "93f5de16-693b-416e-8d63-2368f2b34a44",
    "sourceUuid": "9793f526-d01b-4a48-9569-0a72a3096b06",
    "destination": "1AAAA1111xxxxxxxxxxxxxxxxxxy43CZ9j",
    "token": "SOUP",
    "quantity": 500000000,
    "deliveryDate": "2016-10-22T20:00:00+0000",
    "refData": "test ref data",
    "pseudo": false,
    "holdPromise": false,
    "state": 1,
    "complete": false,
    "deliveryTx": null,
    "updatedAt": "2016-10-21T18:43:21+0000",
    "createdAt": "2016-10-21T18:43:21+0000"
}

Creates a new token delivery. Also registers a new Tokenpass promise and provisional transaction unless hold_promise is true. Checks that the source address has enough inventory to cover this quantity. Pseudo token deliveries skip this check and can use any source address.

HTTP Request

POST https://deliver.tokenly.com/api/v1/delivery

Body Parameters

Parameter Description
source (string) uuid OR bitcoin address of source to retrieve and send token inventory from
destination (string) bitcoin address or a tokenpass username in the form of user:username
token (string) token or pseudo token to delivery
quantity (integer) quantity of token to deliver, in satoshis.
delivery_date (timestamp, Optional) set to null to fulfill only on manual request, or set a date for automatic delivery. This parameter is not allowed for deliveries to usernames.
ref_data (string, Optional) optional extra reference data you can attach
hold_promise (boolean, Optional) default false, true if you want to register a delivery without creating an immediate promise. This parameter may not be true for deliveries to usernames.
pseudo (boolean, Optional) default false, true if using an un-issued (not real) token, makes delivery stuck in promise form and unfulfillable until swapped for a real token delivery.

Get token delivery details

DELIVER_UUID="8ccccccc-1234-5678-1234-cccccccc1111"

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "GET\nhttps://deliver.tokenly.com/api/v1/delivery/${DELIVER_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://deliver.tokenly.com/api/v1/delivery/$DELIVER_UUID
<?php

$client = new Tokenly\DeliveryClient\Client('https://deliver.tokenly.com', $API_TOKEN, $API_SECRET_KEY);

$uuid = "93f5de16-693b-416e-8d63-2368f2b34a44";

$response = $client->getDelivery($uuid);

The above command returns data structured like the following:

{
    "id": "93f5de16-693b-416e-8d63-2368f2b34a44",
    "sourceUuid": "9793f526-d01b-4a48-9569-0a72a3096b06",
    "destination": "1AAAA1111xxxxxxxxxxxxxxxxxxy43CZ9j",
    "token": "SOUP",
    "quantity": 500000000,
    "deliveryDate": "2016-10-22T20:00:00+0000",
    "refData": "test ref data",
    "pseudo": false,
    "holdPromise": false,
    "state": 1,
    "complete": false,
    "deliveryTx": null,
    "updatedAt": "2016-10-21T18:43:21+0000",
    "createdAt": "2016-10-21T18:43:21+0000"
}

Gets details and current status of a delivery. State is 0, 1 or 2. 0 is pending, 1 is ready and 2 is sent.

HTTP Request

GET https://deliver.tokenly.com/api/v1/delivery/{deliveryId}

URL Parameters

Parameter Description
deliveryId The UUID of the delivery

Get a list of Deliveries

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "GET\nhttps://deliver.tokenly.com/api/v1/delivery\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://deliver.tokenly.com/api/v1/delivery
<?php

$client = new Tokenly\DeliveryClient\Client('https://deliver.tokenly.com', $API_TOKEN, $API_SECRET_KEY);

$response = $client->getDeliveryList();

The above command returns data structured like the following:

{
    "count": 2,
    "items": [
        {
            "id": "c78bcedc-3c18-4d22-b676-8c1d5f1d207b",
            "sourceUuid": "1f8a1fc4-039a-48ff-a45c-150812044b69",
            "destination": "3LaaKdhrYQHzWxCeB3Kvd3xs3kKJUzqdFn",
            "token": "PIZZA",
            "quantity": "1000000000",
            "deliveryDate": "2016-10-22T20:57:28+0000",
            "refData": "{\"test\": true}",
            "pseudo": false,
            "holdPromise": false,
            "state": 1,
            "complete": false,
            "deliveryTx": null,
            "updatedAt": "2016-10-21T20:57:28+0000",
            "createdAt": "2016-10-21T20:57:28+0000"
        },
        {
            "id": "2ef604c6-ae4e-4905-aa93-de633188019b",
            "sourceUuid": "1f8a1fc4-039a-48ff-a45c-150812044b69",
            "destination": "12Hord1dcvug4r25UXCCNTy12Lhk49JEat",
            "token": "SOUP",
            "quantity": "1000000000",
            "deliveryDate": "2016-10-22T20:57:28+0000",
            "refData": "{\"test\": true}",
            "pseudo": false,
            "holdPromise": false,
            "state": 1,
            "complete": false,
            "deliveryTx": null,
            "updatedAt": "2016-10-21T20:57:28+0000",
            "createdAt": "2016-10-21T20:57:28+0000"
        }
    ]
}

Returns a list of all deliveries owned by the authenticated user.

HTTP Request

GET https://deliver.tokenly.com/api/v1/delivery

Request Parameters

Parameter Description
source (string) optional filter for deliveries from specific source UUID
token (string) optional filter for deliveries of a specific token
destination (string) optional filter for delivery destination
show_complete (boolean) default false, set to true to include complete deliveries in list.

Update an existing delivery

DELIVERY_UUID="8ccccccc-1234-5678-1234-cccccccc1111"

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "PATCH\nhttps://deliver.tokenly.com/api/v1/source/${DELIVERY_UUID}\n{\"quantity\": 600000000}\n${API_TOKEN}\n${NONCE}" \
    | openssl dgst -sha256 -hmac "${API_SECRET_KEY}" -binary | base64)

curl -X PATCH \
    -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 '{"quantity": 600000000}' \
    https://deliver.tokenly.com/api/v1/source/${DELIVERY_UUID}
<?php

$client = new Tokenly\DeliveryClient\Client('https://deliver.tokenly.com', $API_TOKEN, $API_SECRET_KEY);

$uuid = "93f5de16-693b-416e-8d63-2368f2b34a44";
$data = [
    'quantity' => 600000000,
];
$response = $client->updateDelivery($uuid, $data);

The above command returns data structured like this:

{
    "id": "93f5de16-693b-416e-8d63-2368f2b34a44",
    "sourceUuid": "9793f526-d01b-4a48-9569-0a72a3096b06",
    "destination": "1AAAA1111xxxxxxxxxxxxxxxxxxy43CZ9j",
    "token": "SOUP",
    "quantity": 600000000,
    "deliveryDate": "2016-10-22T20:00:00+0000",
    "refData": "test ref data",
    "pseudo": false,
    "holdPromise": false,
    "state": 1,
    "complete": false,
    "deliveryTx": null,
    "updatedAt": "2016-10-21T18:43:21+0000",
    "createdAt": "2016-10-21T18:43:21+0000"
}

Update an existing delivery. Some fields are allowed to be changed.

HTTP Request

PATCH https://deliver.tokenly.com/api/v1/source/{deliveryId}

URL Parameters

Parameter Description
deliveryId The UUID of the delivery

Body Parameters

Parameter Description
quantity (integer) in satoshis. The changed amount must still be available in the source address
delivery_date (timestamp
ref_data (string) update optional extra reference data
ready (boolean) mark this delivery as ready for fulfillment. Deliveries to usernames cannot be marked ready.

Delete a delivery

DELIVERY_UUID="8ccccccc-1234-5678-1234-cccccccc1111"

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

curl -X DELETE \
    -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}" \
    https://deliver.tokenly.com/api/v1/source/${DELIVERY_UUID}
<?php

$client = new Tokenly\DeliveryClient\Client('https://deliver.tokenly.com', $API_TOKEN, $API_SECRET_KEY);

$uuid = "93f5de16-693b-416e-8d63-2368f2b34a44";
$response = $client->cancelDelivery($uuid);

The above command returns data structured like this:

{
    "result": true
}

Cancels an unfulfilled delivery and removes any related Tokenpass promise.

HTTP Request

DELETE https://deliver.tokenly.com/api/v1/source/{deliveryId}

URL Parameters

Parameter Description
deliveryId The UUID of the delivery

Fulfillment Methods

Fulfillment send tokens on the blockchain for existing deliveries. A delivery must be marked ready to be fulfilled.

Fulfill a Single Delivery

DELIVERY_UUID="8ccccccc-1234-5678-1234-cccccccc1111"

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "POST\nhttps://deliver.tokenly.com/api/v1/fulfillment/single/${DELIVERY_UUID}\n{}\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 '{}' \
    https://deliver.tokenly.com/api/v1/fulfillment/single/${DELIVERY_UUID}
<?php

$client = new Tokenly\DeliveryClient\Client('https://deliver.tokenly.com', $API_TOKEN, $API_SECRET_KEY);

$uuid = "8ccccccc-1234-5678-1234-cccccccc1111";

$response = $client->fulfillSingleDelivery($uuid);

The above command returns data structured like this:

{
  "result": true
}

Initiates a multi-sig payment proposal for fulfilling a single delivery on the blockchain. The delivery to send must be marked ready. The client holding the remaining multisig keys will need to sign the transaction in their wallet or with their application. After the transaction is created and broadcasted, the delivery_tx field is updated and the sent field set to true. After the transaction is confirmed by the network it is marked complete.

HTTP Request

POST https://deliver.tokenly.com/api/v1/source/{deliveryId}

URL Parameters

Parameter Description
deliveryId The UUID of the delivery

Fulfill Multiple Deliveries from a Source Address

SOURCE_ADDRESS_UUID="8ccccccc-1234-5678-1234-cccccccc1111"

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SIGNATURE=$(echo -en "POST\nhttps://deliver.tokenly.com/api/v1/fulfillment/multiple/${SOURCE_ADDRESS_UUID}\n{\"tokens\":[\"MYCOIN\",\"YOURCOIN\"]}\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 '{"tokens":["MYCOIN","YOURCOIN"]}\n${API_TOKEN}' \
    https://deliver.tokenly.com/api/v1/fulfillment/multiple/${SOURCE_ADDRESS_UUID}
<?php

$client = new Tokenly\DeliveryClient\Client('https://deliver.tokenly.com', $API_TOKEN, $API_SECRET_KEY);

$source_address_uuid = "8ccccccc-1234-5678-1234-cccccccc1111";
$filters = [
    'tokens' => [ 'MYCOIN', 'YOURCOIN' ]
];
$response = $client->fulfillMultipleDeliveries($source_address_uuid, $filters);

The above command returns data structured like this:

{
  "result": true
}

Groups together all ready deliveries from the specified source address and creates the multi-sig payment proposals for delivering the inventory. The delivery to send must be marked ready. All multisig proposals are initiated and wallets holding the remaining keys must sign the transaction to complete the payments.

An optional array of tokens can be included to limit which tokens are sent.

HTTP Request

POST https://deliver.tokenly.com/api/v1/source/{deliveryId}

URL Parameters

Parameter Description
deliveryId The UUID of the delivery. This can also be the bitcoin address of the source address.

Body Parameters

Parameter Description
tokens (string

Issuance Methods

Propose an issuance transaction to create a new token, or issue more of an existing token.

Create a new issuance

API_TOKEN="Txxxxxxxxxxxxxxx"
API_SECRET_KEY="Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
NONCE=`date +%s`
SOURCE="9793f526-d01b-4a48-9569-0a72a3096b06"
SIGNATURE=$(echo -en "POST\nhttps://deliver.tokenly.com/api/v1/issuance/${SOURCE}\n{\"asset\": \"MYNEWTOKEN\", \"divisible\": true, \"quantity\": 50, \"description\": \"About my new token\"}\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 '{"asset": "MYNEWTOKEN", "divisible": true, "quantity": 50, "description": "About my new token"}' \
    https://deliver.tokenly.com/api/v1/issuance/${SOURCE}
<?php

$client = new Tokenly\DeliveryClient\Client('https://deliver.tokenly.com', $API_TOKEN, $API_SECRET_KEY);

$source      = "9793f526-d01b-4a48-9569-0a72a3096b06";
$asset       = "MYNEWTOKEN";
$divisible   = true;
$quantity    = 50;
$description = "About my new token";

$response = $client->createIssuance($source, $asset, $quantity, $divisible, $description);

The above command returns data structured like this:

{
    "id": "24de3274-8415-46e1-9d48-6964982970ed",
    "quantity": 10,
    "asset": "A1000000555555560001",
    "copayTransaction": {}
}

Creates a new token issuance.

HTTP Request

POST https://deliver.tokenly.com/api/v1/issuance/{source}

URL Parameters

Parameter Description
source The UUID of the source address

Body Parameters

Parameter Description
source (string) uuid OR bitcoin address of source to retrieve and send token inventory from
token (string) token or pseudo token to issuance
quantity (integer) quantity of token to deliver, in satoshis
divisible (boolean) Whether the token is divisible or not
description (string) A text description or BVAM hash

Errors

The Token Delivery Service API uses the following error codes:

Error Code Name Meaning
400 Bad Request The data contained a syntax error or was invalid
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
422 Unprocessable Entity The data was valid, but violated one or more validation rules
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.