Asset creation API

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

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

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: