This API allows you to automate the process of creating CoinSpark assets.

Any bitcoin wallet can create a CoinSpark asset by sending a transaction containing the appropriate metadata. As part of this process, the asset contract must be generated, since its content affects the asset hash embedded inside that metadata.

To make this process easier, we provide an asset creation API which parallels the manual asset creation form on this site. The API enables scripts and processes to create assets via a simple JSON-RPC request, as part of a broader workflow. From the perspective of end users, there is no difference between assets created via the web form and those created via the API.

To get started with the asset creation API, please contact us to receive your API credentials. These consist of:

  • Your unique API key to be sent in the key parameter of API requests.
  • A bitcoin address which you fund to cover the cost of asset creation transactions.
  • A testnet address which you fund to cover asset creation transactions on testnet.

By default, each successful asset creation costs BTC 0.0002, which is deducted from the funds you have provided. This comes from BTC 0.0001 sent to the recipient of the new asset plus a transaction fee of BTC 0.0001 collected by miners. It is possible to reduce the cost 10x to BTC 0.00002 by providing the appropriate API parameters, however this may cause a delay in the bitcoin network confirming the genesis transaction.

The funds which you provide to cover your asset creation transactions are held by bitcoind, running on our servers, with a wallet account and address that is unique to you. We recommend keeping as little funds as possible in your account, and topping it up regularly. The remaining balance in your account is returned in the response to successful API calls, and can also be checked using a blockchain explorer such as Blockchain.info.

The asset creation API is accessed using the same JSON-RPC protocol as used by the Bitcoin Core software. The query is sent in JSON format within the raw payload of an POST request to https://coinspark.org/api/ with the method coinspark_create_asset, and the response is also provided in JSON format. Note that, in order to protect your API key, requests must be sent over HTTPS rather than unsecured HTTP.

Example create asset request

This example contains the required parameters only. See the full list of parameters below.

{
    "id": "any_request_id",
    "method": "coinspark_create_asset",
    "params": {
        "key": "f8sK30M394dS04LkdpWf",
        "asset_url": "http:\/\/john-smiths.com\/vouchers\/",
        "contract_url": "http:\/\/john-smiths.com\/vouchers\/contract.pdf",
        "issuer": "John Smith Restaurants",
        "issuer_address": "123 Cookery Street\nLondon\nEC2V 6DN\nUnited Kingdom",
        "name": "Voucher for John Smith Restaurants",
        "name_short": "John Smith Voucher",
        "description": "Voucher for the purchase of food and drink at any branch of John Smith Restaurants in the European Union. Breakfasts are excluded.",
        "raw_quantity": 100000000,
        "display_multiple": 0.01,
        "value_per_unit": "1 Euro",
        "send_to_address": "ssw5De84Cm5BynnWsuF9cXZmFp4bb3fNEeqvh"
    }
}

Example create asset response

{
    "id": "any_request_id",
    "result": {
        "txid": "1856ebbfd8f993ae9133af7538bd0498d7babffda5344dfc704e4762a21081d3",
        "spent_btc": 0.0002,
        "balance_btc": 0.00742,
        "contract_final": "http:\/\/coinspark.org\/create-asset\/?id=18064221484817928599&file=contract",
        "web_page_basic": "http:\/\/coinspark.org\/create-asset\/?id=18064221484817928599&file=home",
        "web_page_fields": {
            "name": "Voucher for John Smith Restaurants",
            "issuer": "John Smith Restaurants",
            "description": "Voucher for the purchase of food and drink at any branch of John Smith Restaurants in the European Union. Breakfasts are excluded.",
            "units": "1 Euro",
            "multiple": 0.01,
            "issue_date": "2014-11-20T12:24:50+00:00",
            "expiry_date": "",
            "interest_rate": 0,
            "genesis_txid": "1856ebbfd8f993ae9133af7538bd0498d7babffda5344dfc704e4762a21081d3",
            "name_short": "John Smith Voucher",
            "contract_url": "http:\/\/john-smiths.com\/vouchers\/contract.pdf",
            "coinspark_tracker_url": [
                "assets2.coinspark.org",
                "assets3.coinspark.org",
                "assets1.coinspark.org"
            ]
        }
    },
    "jsonrpc": "2.0"
}

Create asset request parameters

Parameter Description Example Required? Default
key your API key "f8sK30M394dS04LkdpWf" Yes
testnet whether to create the asset in testnet false No false
asset_url full absolute URL of (future) asset web page (see note below) "http://example.com/asset/" Yes
contract_url full absolute URL where you will host the asset contract "http://example.com/asset/contract.pdf" Yes
issuer legal name of asset issuer "John Smith Restaurants" Yes
issuer_address registered address of issuer "123 Cookery St\nLondon\nEC2V 6DN\nUK" Yes
name full name of asset for contract "Voucher for John Smith Restaurants" Yes
name_short short name of asset for display "John Smith Voucher" Yes
description explanation of underlying value "Voucher for the purchase of ..." Yes
raw_quantity number of raw asset units, max 1014 100000000 Yes
display_multiple multiple from raw to display units 100 Yes
value_per_unit real-world value per display unit "1 Euro" Yes
send_to_address CoinSpark address to send asset "ssw5De84Cm5BynnWsuF9cXZmFp4bb3fNEeqvh" Yes
contract_template Contract template to use ("us", "uk", or URL of your own) "us" No "uk"
governing_law Governing law for asset contract "Singapore law" No "English law"
expiry_timestamp Unix timestamp when asset will expire (omit or null for no expiry) 1731847656 No null
charge_basis_points Per-transaction charge in 100ths of a percent, maximum 250 125 No 0
charge_flat_raw_qty Per-transaction charge in raw units, maximum 5000 8 No 0
rounding API parameter rounding (-1, 0 or 1 – see note below) -1 No 1
send_btc total bitcoin to send with new asset 0.0005 No 0.0001
num_outputs units of new asset spread over how many transaction outputs 4 No 1
fee_btc how much bitcoin to send as the (miner) transaction fee 0.0002 No 0.0001
confirmations how many confirmations required to redeem the asset (for contract) 1 No 6 (1 hour)
residents which countries’ residents can redeem the asset (for contract) "USA and Canada" No "n/a"
prohibited where forbidden to send asset (for contract) "North Korea" No "n/a"

The asset_url parameter determines the useHttps, domainName, usePrefix and pagePath fields in the genesis metadata. The URL may use the http:// or https:// protocol and any valid domain name, but no HTTP username or password. Its path must take the form /asset-name/ or /coinspark/asset-name/ where asset-name can only contain lower case letters, numbers, hyphens (-) or full stops (.). It is recommended to keep asset URLs short, since long ones may leave insufficient bytes remaining for the asset hash. In this case the API will return an error.

To save space in OP_RETURNs, which are limited to 40 bytes in Bitcoin Core 0.9, the CoinSpark protocol places a limit on the accuracy for representing raw asset quantities in genesis transactions. It allows three significant digits for the number of raw units created, and two significant digits for flat per-transaction fees. The rounding parameter determines how the raw_quantity and charge_flat_raw_qty values are modified if they cannot be represented exactly with this limitation. Values of -1, 0 and 1 respectively mean: round down, round to the nearest, round up.

Create asset response fields

Field Description
txid Bitcoin transaction ID of asset genesis transaction.
spent_btc The quantity of your bitcoin spent on this asset creation.
balance_btc The quantity of bitcoin remaining in your account.
contract_final The URL from which you can download the asset contract. To make the asset valid, you must make this contract available at the contract_url you provided in the request. The contract cannot be changed after the asset is created because it is used to calculate the asset hash in the genesis transaction.
web_page_basic The URL from which you can download a basic asset web page which is ready to go. To make the asset valid, you must make this web page (or another valid one) available at the asset_url you provided in the request.
web_page_fields If you wish to create your own asset web page, these fields should be included in the JSON asset specification embedded on the page. Ensure you embed the JSON inside the asset web page correctly, including \uXXXX-escaping the characters ( ) < >. You may modify or add to these fields, so long as you do not change those used to calculate the asset hash.

Create asset failure response

If there was an error with the JSON-RPC request, the result element will not be present, and instead the response will contain an error, such as:

{
    "id": "any_request_id",
    "error": {
        "code": -20003,
        "message": "Insufficient funds are available in your account",
        "data": "address: 1C8XH7ZFjRWj7w3BwAvMCKyU2hHtjvFGFM, required: 0.0003, available: 0.0001 BTC"
    },
    "jsonrpc": "2.0"
}

The following error code may be present:

code message meaning
-20000 Protocol error The API must be called using https
-20001 Invalid key The API key does not appear to be valid
-20002 Insufficient funds Insufficient funds are available in your account
-32700 Invalid JSON received The JSON request did not contain valid JSON
-32600 Invalid JSON-RPC request The request was not valid JSON-RPC
-32601 Method not found The method in the request is not available
-32602 Invalid params The method params in the request are not valid
-32603 Internal error Something went wrong internally