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 |