Primechain-API Endpoints

Blockchain administration

Blockchain parameters


Use get /api/v1/blockchain_params to view the blockchain parameters.

Response:

{
	"status": 200,
	"blockchain_params": {
		"chain-protocol": "multichain",
		"chain-description": "MultiChain primechain-api",
		"root-stream-name": "root",
		"root-stream-open": false,
		"chain-is-testnet": false,
		"target-block-time": 10,
		"maximum-block-size": 1000000000,
		"default-network-port": 61172,
		"default-rpc-port": 15590,
		"anyone-can-connect": false,
		"anyone-can-send": false,
		"anyone-can-receive": false,
		"anyone-can-receive-empty": true,
		"anyone-can-create": false,
		"anyone-can-issue": false,
		"anyone-can-mine": false,
		"anyone-can-activate": false,
		"anyone-can-admin": false,
		"support-miner-precheck": true,
		"allow-arbitrary-outputs": false,
		"allow-p2sh-outputs": true,
		"allow-multisig-outputs": true,
		"setup-first-blocks": 60,
		"mining-diversity": 0.3,
		"admin-consensus-upgrade": 0.5,
		"admin-consensus-admin": 0.5,
		"admin-consensus-activate": 0.5,
		"admin-consensus-mine": 0.5,
		"admin-consensus-create": 0,
		"admin-consensus-issue": 0,
		"lock-admin-mine-rounds": 10,
		"mining-requires-peers": false,
		"mine-empty-rounds": 10,
		"mining-turnover": 0.5,
		"first-block-reward": -1,
		"initial-block-reward": 0,
		"reward-halving-interval": 52560000,
		"reward-spendable-delay": 1,
		"minimum-per-output": 0,
		"maximum-per-output": 100000000000000,
		"minimum-relay-fee": 0,
		"native-currency-multiple": 100000000,
		"skip-pow-check": true,
		"pow-minimum-bits": 4,
		"target-adjust-freq": -1,
		"allow-min-difficulty-blocks": false,
		"only-accept-std-txs": true,
		"max-std-tx-size": 100000000,
		"max-std-op-returns-count": 1024,
		"max-std-op-return-size": 67108864,
		"max-std-op-drops-count": 100,
		"max-std-element-size": 32768,
		"chain-name": "primechain-api",
		"protocol-version": 10011,
		"network-message-start": "f2e1ccf2",
		"address-pubkeyhash-version": "00c4bbce",
		"address-scripthash-version": "05f724b2",
		"private-key-version": "80e9f374",
		"address-checksum-value": "97582e9c",
		"genesis-pubkey": "03bb8ca6bc395d6638ab1bc9a7e8a34ef10b894663bef065ee0d5966c43f8adabc",
		"genesis-version": 1,
		"genesis-timestamp": 1543911518,
		"genesis-nbits": 537919487,
		"genesis-nonce": 3,
		"genesis-pubkey-hash": "b180acd07afad0857f3993da10cfd7342e20208a",
		"genesis-hash": "0a5648249009b26040a0305af1d7cdd463311a12d95db0264ecbb6beef4f8941",
		"chain-params-hash": "ee65fb033910ff0703e02a3bfd5ccb5b89cd111c59e8582f80a4616b5b2d16fb"
	}
}


Sample code:


Runtime parameters


To get a selection of this node's runtime parameters (these are set when the node starts up), use get /api/v1/runtime_params

Response:

{
"status": 200,
	"runtime_params": {
		"port": 61172,
		"reindex": false,
		"rescan": false,
		"txindex": true,
		"autocombineminconf": 1,
		"autocombinemininputs": 50,
		"autocombinemaxinputs": 100,
		"autocombinedelay": 1,
		"autocombinesuspend": 15,
		"autosubscribe": "",
		"handshakelocal": "1Qr572HfZyxmburpA6fQY4Nu2k7uWVR5dwwBoe",
		"bantx": "",
		"lockblock": "",
		"hideknownopdrops": false,
		"maxshowndata": 16384,
		"miningrequirespeers": false,
		"mineemptyrounds": 10,
		"miningturnover": 0.5,
		"lockadminminerounds": 10,
		"gen": true,
		"genproclimit": 1
	}
}


Sample code:


Blockchain information


Use get /api/v1/blockchain_info to get general information about this node and blockchain.

Response:

{
	"status": 200,
	"blockchain_info": {
		"version": "1.0.6",
		"nodeversion": 10006901,
		"protocolversion": 10011,
		"chainname": "primechain-api",
		"description": "MultiChain primechain-api",
		"protocol": "multichain",
		"port": 61172,
		"setupblocks": 60,
		"nodeaddress": "primechain-api@169.63.131.118:61172",
		"burnaddress": "1XXXXXXXM4XXXXXXiqXXXXXXdyXXXXXXc7qCdr",
		"incomingpaused": false,
		"miningpaused": false,
		"walletversion": 60000,
		"balance": 0,
		"walletdbversion": 2,
		"reindex": false,
		"blocks": 81,
		"timeoffset": 0,
		"connections": 3,
		"proxy": "",
		"difficulty": 0,
		"testnet": false,
		"keypoololdest": 1543915768,
		"keypoolsize": 2,
		"paytxfee": 0,
		"relayfee": 0,
		"errors": "",
		"chain": "main",
		"chain_name": "primechain-api",
		"description_": "MultiChain primechain-api",
		"protocol_": "multichain",
		"setup_blocks": 60,
		"re_index": false,
		"blocks_": 81,
		"headers": 81,
		"bestblockhash": "0166ed431644e7a6f768ac2ad5b3904e13a158be729cd5873854fffb01821007",
		"difficulty_": 0,
		"verificationprogress": 1,
		"chainwork": "0000000000000000000000000000000000000000000000000000000000000520",
		"chainrewards": 0
	}
}


Sample code:

Notes:

  1. The bestblockhash of the most recent block on the active chain can be compared across nodes to check if they are perfectly synchronized.
  2. The burnaddress is an address with no known private key. Assets can be sent to the burnaddress to make them provably unspendable.
  3. The nodeaddress can be passed to other nodes for connecting.
  4. The setupblocks field gives the length in blocks of the setup phase in which some consensus constraints are not applied.


Memory pool information


The memory pool contains transactions that the node has seen and validated, but which have not yet been confirmed on the active chain. To get information about the memory pool, use get /api/v1/mempool_info

Response:

{
  "status": 200,
  "mempool_info": 
    {
      "size": 0,
      "bytes": 0
    }
}


Sample code:


Note: If the memory pool is growing continuously, this suggests that transactions are being generated faster than the network is able to process them.


Raw memory pool


For a list of transaction IDs which are in the node's memory pool, use get /api/v1/raw_mempool

Response:

{
  "status": 200,
  "raw_mempool": [],
}


Sample code:


List blocks


Use post /api/v1/list_blocks for information about the blocks specified, on the active chain only.

List blocks 10 to 12


Request body:
{
	"block_number":"10-12"
}

Response:
{
	"status": 200,
	"list_blocks": [
		{
			"hash": "068c42ca81014ecddb9dedbd00e9256f823babd539aef30e580229dee79c1821",
			"miner": "1QzSTNf9pCBCPGxSFHYWEzdkCWiKeThgv4Hkmt",
			"confirmations": 72,
			"height": 10,
			"time": 1543911612,
			"txcount": 1
		},
		{
			"hash": "040d8d8b1913fb25fef5f995054ada332db4d7c32e322e5344fe53264caf124d",
			"miner": "1QzSTNf9pCBCPGxSFHYWEzdkCWiKeThgv4Hkmt",
			"confirmations": 71,
			"height": 11,
			"time": 1543911621,
			"txcount": 1
		},
		{
			"hash": "0f07a552f2801a198cd5d3f2c2e989379bb60427d3ad4bc4fc22c0060014dc79",
			"miner": "1QzSTNf9pCBCPGxSFHYWEzdkCWiKeThgv4Hkmt",
			"confirmations": 70,
			"height": 12,
			"time": 1543911637,
			"txcount": 1
		}
	]
}


Sample code:


List blocks 8, 14 and 23


Request body:
{
	"block_number":"8,14,23"
}

Response:
{
	"status": 200,
	"list_blocks": [
		{
			"hash": "0ff1c0dd9ae284766e1150d1eee8b4dc34bae6e75935849f4b41e0e720337270",
			"miner": "1QzSTNf9pCBCPGxSFHYWEzdkCWiKeThgv4Hkmt",
			"confirmations": 74,
			"height": 8,
			"time": 1543911597,
			"txcount": 1
		},
		{
			"hash": "08294da3838341b76bc8003dd891f4156b08748a20c45517960d229eac10e525",
			"miner": "1QzSTNf9pCBCPGxSFHYWEzdkCWiKeThgv4Hkmt",
			"confirmations": 68,
			"height": 14,
			"time": 1543911653,
			"txcount": 1
		},
		{
			"hash": "09e6467214f9bd1e0696a9e146cdb635a898c6f325d1af0eba7dd00fc12f6ee0",
			"miner": "1QzSTNf9pCBCPGxSFHYWEzdkCWiKeThgv4Hkmt",
			"confirmations": 59,
			"height": 23,
			"time": 1543911745,
			"txcount": 1
		}
	]
}


Sample code:


Peer info


Use get /api/v1/peer_info for information about the other nodes to which this node is connected. The output will be something like this:

Response:

{
	"status": 200,
	"peer_info": [
		{
			"id": 5,
			"addr": "169.63.131.125:61172",
			"addrlocal": "169.63.131.118:43376",
			"services": "0000000000000001",
			"lastsend": 1543919288,
			"lastrecv": 1543919288,
			"bytessent": 24378,
			"bytesrecv": 22834,
			"conntime": 1543915962,
			"pingtime": 0.06828,
			"version": 70002,
			"subver": "/MultiChain:0.1.0.11/",
			"handshakelocal": "1Qr572HfZyxmburpA6fQY4Nu2k7uWVR5dwwBoe",
			"handshake": "1aMiTQjLXABeoKtVgBcr5zzVXtT1eRvRTfY3RJ",
			"inbound": false,
			"startingheight": 81,
			"banscore": 0,
			"synced_headers": 81,
			"synced_blocks": 81,
			"inflight": [],
			"whitelisted": false
		},
		{
			"id": 6,
			"addr": "10.188.200.228:61172",
			"addrlocal": "10.188.200.225:59178",
			"services": "0000000000000001",
			"lastsend": 1543919289,
			"lastrecv": 1543919289,
			"bytessent": 22920,
			"bytesrecv": 22895,
			"conntime": 1543915963,
			"pingtime": 0.067716,
			"version": 70002,
			"subver": "/MultiChain:0.1.0.11/",
			"handshakelocal": "1Qr572HfZyxmburpA6fQY4Nu2k7uWVR5dwwBoe",
			"handshake": "1aMiTQjLXABeoKtVgBcr5zzVXtT1eRvRTfY3RJ",
			"inbound": false,
			"startingheight": 81,
			"banscore": 0,
			"synced_headers": 81,
			"synced_blocks": 81,
			"inflight": [],
			"whitelisted": false
		},
		{
			"id": 7,
			"addr": "52.172.139.41:61172",
			"addrlocal": "169.63.131.118:57018",
			"services": "0000000000000001",
			"lastsend": 1543919290,
			"lastrecv": 1543919291,
			"bytessent": 22804,
			"bytesrecv": 22926,
			"conntime": 1543915964,
			"pingtime": 0.261546,
			"version": 70002,
			"subver": "/MultiChain:0.1.0.11/",
			"handshakelocal": "1Qr572HfZyxmburpA6fQY4Nu2k7uWVR5dwwBoe",
			"handshake": "1QzSTNf9pCBCPGxSFHYWEzdkCWiKeThgv4Hkmt",
			"inbound": false,
			"startingheight": 81,
			"banscore": 0,
			"synced_headers": 81,
			"synced_blocks": 81,
			"inflight": [],
			"whitelisted": false
		}
	],
}


Sample code:


Entity creation & permissions management

Creating a new entity


To create a new entity, use post /api/v1/create_entity.The following are generated:

  • a public key (If external_key_management is set to true),
  • a private key (If external_key_management is set to true)
  • a blockchain address.
  • RSA private key (If generate_rsa_keys is set to true),
  • RSA public key (If generate_rsa_keys is set to true)


Request body:

{
  "external_key_management": true,
  "generate_rsa_keys": true
}

Response:
{
    "status": 200,
    "response": {
      "primechain_address": "1Zj8hJiAtR5UaZkrzWhsRwU1s6DYBQULeCx3Ro",
      "primechain_private_key": "VFGxBp56YTFwAkwtLn3rxKh4ah8JYRtKf2Kb3YkKyTqFnD1XdyWXmPX6",
      "primechain_public_key": "03b085ad524868aa32ba05109bf0448b188bfd3627fde1c91c127d938c07815879",
      "primechain_private_key": "VGFuvDqexth6GZPSkAXwZwEyQ9Y8LHFokUH2BwkcdvRPcGvF5HUy9euk",
      "primechain_public_key": "035f3609b3ddb799946a6cbdf49820552ac9fed49ea10d954cdc4b1caf90cf88c4",
      "rsa_private_key": "-----BEGIN PRIVATE KEY----- MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCUX/V0STFvx1Yh OEuCXVjqgPVZq4XxbBJj/P3/8vAsC498VyEgmy4rbWKS1+pSFt6ex8YDt1yZZroP N4Tg1I/jOk1YH/5rB7lmV+uv/g7WvE3FWEDRnDjbZBxClV4AhaZvOI5cR542BSii GfOVf4NqULMmjdVkdPxiJ8pl1mr9iy/LTC7gaD4RJ27kztNPUO+xsWoee5wtTlEv IUOKr/PwQIyBmu4uXXiVbVsNLlq7oFJ2yxHDcPVVI8klHRoiCjzwZvM05VY6xk5s DCysJ9EzpeBdwO84Qvqkr2I9NYLDFnr7yVYUYA72RcSbl+tPev1Oq7v0/qKlcJX5 XBajebzJAgMBAAECggEATqz/W3UAONRLUHwoVe0nm9lbv/uan6R9r/VTvidUwRY0 NGuDDmYauj5bWaASCQtFao5l6kyNVm5JVI5M8GbmEUg2APeeEaTb42/VctHVjnn1 ByK/5CXhZDwWXBwV51L3KNylaDs1olFj9WirZ+dgiLxX8qacs5LwzR9qTEvBGcWn CSgD1Yw60nQS9Y7NXkV0GHhSp7YXa+lXnG6cMEYqqxHD9GTD2p/SaoPf4t0ajobE 6ZH9UfbapRUPATTF5X0S+UqPfNUthCOvzSzX/bfrBECpwAAB4TWeinqJA3EpYw/j 9sbTGBenxZwhxIEs0On4WM3dV8HZJv+tSwo05ZpG7QKBgQDcTGijkH4R9bYE50OQ DLEdCmAE2gdJpxG0bEGFuF+AmuRT2mtmapMlsAx6udDuckUbRMbjqC9UjnxXqeEI dyuqf2SDDt3JhD23/Gk/qylld95w1LMueZY+SwYrWvjyydJE8sVjj78Kc6X2vuAB uDyB6geg+kVVcd1QyRgqmh4crwKBgQCsa6HGP7rJeDDCyKzL5aw0HZKJ0DW2O4hp asJjVHWDRfInzAGn9jXa62b5EoI1jCApNBoRPn1vCVq0K4z9zCypt66A62wrNIKI W/34NFkEtYMpQJE2Y6uYgrNGDy3yuPuNnOkl8/TQlJmEf/ykMEJepIBYq759BvTa zuVivM1MBwKBgQCPt91wD7zfdKAptMIUAOOvIWyg3ahxeWgIf7ODTFQpr2MT/WOh rhePN7n8eqr+VFgXQRhLvxYZoNcnzbD8d9pp4bAt/A3fAMHO/QGgwsY/5yKcE3dN 84571zAQKspMgjQGPSdfG5EzfV0hi0bSeGIpEwelEoEXDDCpGngEmwTYCwKBgQCU ZSpd6znC7mvhKT/3WRvl2tHlRMsFpaVZPWZCgU2GhyvMbru6KKDfYx1EH1br6UdA zzPkRYlFiKKFULpPMWv7Qjixgm2dndr+q1YhSkSXVfWmCokwa4Yjg9Hx6Vyde/Id RsAvRxEcd9jM/i6dzV9B/4jrSB1xlAwnSkyIt4Bl/wKBgEzqce+tYkn6NxbVcRiQ W6D/UXj1kP9HWYFnI4xWj5Zp9H54yuhZ//gzAf4qB9XYnrOHy3t3mu08/Yrg9F14 +YBHwQD8Gu3qTpw9vFfKXgJs2J8zt/0ePmgg+5rOho833WkKU0qJxhTSu5RcqYFp rYQDaP11oooPIHZr/yHMRI2/ -----END PRIVATE KEY-----",
      "rsa_public_key": "-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlF/1dEkxb8dWIThLgl1Y 6oD1WauF8WwSY/z9//LwLAuPfFchIJsuK21iktfqUhbensfGA7dcmWa6DzeE4NSP 4zpNWB/+awe5Zlfrr/4O1rxNxVhA0Zw422QcQpVeAIWmbziOXEeeNgUoohnzlX+D alCzJo3VZHT8YifKZdZq/Ysvy0wu4Gg+ESdu5M7TT1DvsbFqHnucLU5RLyFDiq/z 8ECMgZruLl14lW1bDS5au6BSdssRw3D1VSPJJR0aIgo88GbzNOVWOsZObAwsrCfR 
    }
}


Sample code:


The private key will be stored in your node if external_key_management is set to false. This will not be visible to other nodes. If you don't want the private key stored in the node, then set external_key_management to true


Create multisig address


To create a pay-to-scripthash (P2SH) multisig address and add it to the wallet, use post /api/v1/create_multisig_address. Funds sent to this address can only be spent by transactions signed by nrequired of the specified keys.

Note: The keys used here should have been created using post /api/v1/create_keypair or post /api/v1/create_entity_rsa

Sample input creating a multisig addresss where 2 out of the provided 3 keys need to be used:

{
	"nrequired": 2,
	"primechain_public_key": [
		"02f168e48c0fab361036eb7b7cd39d0f54f5c0450fc573e116900d8c6656a14a7f",
		"03d7997c08cdc430038c2481e1d2cf7db7b964ecd3410128486a1ac896d78c0e88",
		"03ff4dcf31b5b2469bd6332789007e76aac6950c7d99a1c9cb4c6e09b75f181c15"
	]
}


Response:

{
	"status": 200,
	"primechain_address": "4NM46pESGpnvCn8pJmVZpuFepaeUkwKF3YecSM"
}

Note: You should give send, receive permission to all 4 addresses (the multisig as well as the 3 used to create the multisig.)


Sample code:


Manage permissions of an entity


Use post /api/v1/manage_permissions to grant or revoke 1 or more of the following 8 permissions.

  • connect to connect to other nodes and see the blockchain's contents
  • send to send smart blockchain assets to other entities
  • receive to receive smart blockchain assets from other entities
  • issue to issue new smart assets
  • create to create data streams
  • mine to mine blocks
  • activate to change connect, send and receive permissions for other entities
  • admin to change all permissions for other entities, including issue, mine, activate and admin

Request body:

{
  "action": "grant",
  "primechain_address": "1VCeqGYXLaqMtAFtxTNeTzfW8T714us2t3uwYM",
  "permission": "send,receive"
}

The output will be the transaction id of the transaction in which the permissions were granted.

Response:

{
  "status": 200,
  "tx_id": "e39330efc1594e062a1047074231ce97f65f4d71dbf745576bba81504afba923"
}


Note: To revoke permissions, substitute "revoke" in place of "Grant" in the request body.

Sample code:


List all permissions given to an entity


To get a list of all permissions which have been explicitly granted to a specific address, use post /api/v1/listpermissions and pass the primechain address as a parameter.

Request body:

{
	"primechain_address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
}


Response:

{
	"status": 200,
	"primechain_address": [
		{
			"address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"for": null,
			"type": "connect",
			"startblock": 0,
			"endblock": 4294967295,
			"admins": [
				"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
			],
			"pending": []
		},
		{
			"address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"for": null,
			"type": "send",
			"startblock": 0,
			"endblock": 4294967295,
			"admins": [
				"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
			],
			"pending": []
		},
		{
			"address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"for": null,
			"type": "receive",
			"startblock": 0,
			"endblock": 4294967295,
			"admins": [
				"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
			],
			"pending": []
		},
		{
			"address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"for": null,
			"type": "issue",
			"startblock": 0,
			"endblock": 4294967295,
			"admins": [
				"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
			],
			"pending": []
		},
		{
			"address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"for": null,
			"type": "create",
			"startblock": 0,
			"endblock": 4294967295,
			"admins": [
				"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
			],
			"pending": []
		},
		{
			"address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"for": null,
			"type": "mine",
			"startblock": 0,
			"endblock": 4294967295,
			"admins": [
				"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
			],
			"pending": []
		},
		{
			"address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"for": null,
			"type": "admin",
			"startblock": 0,
			"endblock": 4294967295,
			"admins": [
				"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
			],
			"pending": []
		},
		{
			"address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"for": null,
			"type": "activate",
			"startblock": 0,
			"endblock": 4294967295,
			"admins": [
				"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
			],
			"pending": []
		}
	]
}


Sample code:


Information about the addresses in the wallet


To get a list of all permissions which have been explicitly granted to a specific address, use post /api/v1/listpermissions and pass the primechain address as a parameter.

Request body:

{
	"primechain_address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
}


Response:

{
	"status": 200,
	"primechain_address": [
		{
			"address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"for": null,
			"type": "connect",
			"startblock": 0,
			"endblock": 4294967295,
			"admins": [
				"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
			],
			"pending": []
		},
		{
			"address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"for": null,
			"type": "send",
			"startblock": 0,
			"endblock": 4294967295,
			"admins": [
				"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
			],
			"pending": []
		},
		{
			"address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"for": null,
			"type": "receive",
			"startblock": 0,
			"endblock": 4294967295,
			"admins": [
				"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
			],
			"pending": []
		},
		{
			"address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"for": null,
			"type": "issue",
			"startblock": 0,
			"endblock": 4294967295,
			"admins": [
				"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
			],
			"pending": []
		},
		{
			"address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"for": null,
			"type": "create",
			"startblock": 0,
			"endblock": 4294967295,
			"admins": [
				"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
			],
			"pending": []
		},
		{
			"address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"for": null,
			"type": "mine",
			"startblock": 0,
			"endblock": 4294967295,
			"admins": [
				"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
			],
			"pending": []
		},
		{
			"address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"for": null,
			"type": "admin",
			"startblock": 0,
			"endblock": 4294967295,
			"admins": [
				"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
			],
			"pending": []
		},
		{
			"address": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"for": null,
			"type": "activate",
			"startblock": 0,
			"endblock": 4294967295,
			"admins": [
				"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3"
			],
			"pending": []
		}
	]
}


Sample code:


Validate address


To get information about the validity of an address, including whether this node has the address's private key in its wallet, use post /api/v1/validate_address and pass this parameter:

Request body:

{
  "primechain_address": "1Qr572HfZyxmburpA6fQY4Nu2k7uWVR5dwwBoe"
}


Response:

{
	"status": 200,
	"response": {
		"isvalid": true,
		"primechain_address": "1Qr572HfZyxmburpA6fQY4Nu2k7uWVR5dwwBoe",
		"ismine": true,
		"iswatchonly": false,
		"isscript": false,
		"pubkey": "02fc0cbee9f8a649d21628f2c4640d5ce33c115cea64c265db2612e0c3b31dfb26",
		"iscompressed": true,
		"account": "",
		"synchronized": true
	}
}


Sample code:


List entities


To get a list of entities in this node's wallet, use get /api/v1/list_entities.

Response:

{
	"status": 200,
	"primechain_address": [
		"1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
		"1af89TzR7d7N3pqtKrfzQFxz9MYuNvpt2iFBmj",
		"1B14GaGb9KQYy7poHQA4JvrzgRmLs6QFyX4dw6",
		"14gtREapQns3DtYqiS6pke3sShgDmLxVQP6ZeS",
		"1ZYxMuEUjMMaSvCPtS8i4UuLvDu57GrPGQVH7b",
		"13ep2rhnTGiJXCNfqCiqJxw8NoCzN4eKYinSuN",
		"1FWGDnR9evbf4HQNKfeKeYKxRagwckH4Kemsxs",
		"18ZmXBoXpyAUJyGMPJuSK6jxMSvZaqto8E1PzK",
		"1F3Kftk57XJeQsF4jQqURidqZZcQY7UbVMtMcz",
		"1DxwNEoAwyeQszLptyYGJyEN413mzEn4MV9eSR",
		"1E8HozfDmmzemad8TbmL8MnPVpc5TnSEpRzNRD",
		"1C6ecGod2vqP85w8SRW1nquqn8HiynL9jjYzuP",
		"1X3GYYdmtrdZvv99HACeFMNre26w1EiVxNqrJ7",
		"1Xnvg8LsdHJfruJhcQcxrorjmgLEe5sBb9evkr",
		"1Lh4NnTmU4HFx6uN2nkPfWtbNQNT1sqDuwSMcM",
		"1Miao2swgemhAjZNjmmjb3Tv8aGM9DifbxbBKX",
		"1JUoybWwFsYT16K1rpm35SY8tJ8Y3er7dkjZ5D",
		"15AnXVteaDaTb1wBstqxaXN2ixCEereugw7acE",
		"1VtTz3kJvcGhnMBefhayNpzkRHqj5oudKUoXeD"
	]
}


Sample code:


Electronic Signatures

Signing data


To generate a digital signature, use post /api/v1/create_signature and provide 2 parameters:

  • primechain addresss of the signer
  • the data to be signed
The output will be the digital signature.

Request body:

{
  "primechain_address": "1N9VtvZvP3rsw5Rf4Qpi12TWBaDoEwM2BAEsv2",
  "data": "I fear not the man who has practiced 10,000 kicks once, but I fear the man who has practiced one kick 10,000 times."
}


Response:

{
  "status": 200,
  "signature": "H/zH4VWkOv9/Awu7OUEK43Fq1dtBcBxnrzmwOdytpsr0Grw+lPxWgbgh3Dcr4lhwgVOBb7vAoChjUvqxlqnpDAI="
}


Sample code:


Verifying a digital signature


To verify a signature, use post /api/v1/verify_signature and provide 3 parameters:

  • primechain addresss of the signer
  • data
  • digital signature
The output will be true if the signature is valid and false if the signature is invalid or if an error occurs.

Request body:

{
  "primechain_address": "1N9VtvZvP3rsw5Rf4Qpi12TWBaDoEwM2BAEsv2",
  "data": "I fear not the man who has practiced 10,000 kicks once, but I fear the man who has practiced one kick 10,000 times.",
  "signature": "H/zH4VWkOv9/Awu7OUEK43Fq1dtBcBxnrzmwOdytpsr0Grw+lPxWgbgh3Dcr4lhwgVOBb7vAoChjUvqxlqnpDAI="
}


Response:

{
  "status": 200,
  "response": true
}

{
  "status": 200,
  "response": false
}


Sample code:


Sign and store signature in GREAT


To sign data and store the signature in the GREAT (Global Repository of E-signatures And Timestamps) data stream, use post /api/v1/create_save_signature.

The output will be the signature and the id of the transaction in which the signature is stored in the GREAT data stream.

Request body:

{
  "primechain_address": "1N9VtvZvP3rsw5Rf4Qpi12TWBaDoEwM2BAEsv2",
  "data": "I fear not the man who has practiced 10,000 kicks once, but I fear the man who has practiced one kick 10,000 times."
}


Response:

{
	"status": 200,
	"response": {
		"tx_id": "7d861030114ab5fb5b05c3307be04f9408c5e5251daade36996be4afba469bb3",
		"signature": "H/zH4VWkOv9/Awu7OUEK43Fq1dtBcBxnrzmwOdytpsr0Grw+lPxWgbgh3Dcr4lhwgVOBb7vAoChjUvqxlqnpDAI="
	}
}


Sample code:


Data Streams

MultiChain streams enable a blockchain to be used as a general purpose append-only database, with the blockchain providing timestamping, notarization and immutability. A MultiChain blockchain can contain any number of streams, where the data published in every stream is stored by every node. If a node chooses to subscribe to a stream, it will index that stream's contents to enable efficient retrieval in various ways.

Create data stream


To create a new stream on the blockchain with the specified name, use post /api/v1/create_trade_channel with the 5 parameters mentioned below.

The output will be the txid of the transaction creating the stream.

Request body:

{
	"from_address": "17kpbJdha6vt8QjZz3nsctSx2qWK38idttfDV9",
	"type": "stream",
	"stream_name": "TEST_STREAM_8",
	"details": "This is a test data stream",
	"open":true
}


Note:
  • If open is set to true, write permissions need not be explicitly provided. All addresses can write to the stream. If open is set to false, write permissions need to be explicitly provided.
  • The entity creating the stream must have create permission.
  • Publishers must be explicitly granted per-stream write permissions.


Response:

{
  "status": 200,
  "transaction_id": "e6c3f05d1f576fb559d04ab60124fdbd04d0b32605fab2534a81a63ebe0962ac"
}


Sample code:


List data streams


To get information about all the streams created on the blockchain, use get /api/v1/list_data_streams

Response:

{
"stream_details": [
		{
		"name": "root",
		"createtxid": "144db07d12ca680753868c89f058849a5d5ae20c44f4caabe7a90fbd82e1f884",
		"streamref": "0-0-0",
		"open": false,
		"details": {},
		"subscribed": true,
		"synchronized": true,
		"items": 0,
		"confirmed": 0,
		"keys": 0,
		"publishers": 0
		},
		{
		"name": "OFFER_DETAILS_STREAM",
		"createtxid": "a9caefb96930a16b5e2b705914b6a934212d939dfc4ea3d8020d5fff003e3dc2",
		"streamref": "3-265-51881",
		"open": false,
		"details": {
		"purpose": "Stores the offer details"
		},
		"subscribed": true,
		"synchronized": true,
		"items": 0,
		"confirmed": 0,
		"keys": 0,
		"publishers": 0
		},
		{
		"name": "BLOB_STREAM",
		"createtxid": "e0c78df9ac8ccdd1ebe34a821f7f1a5791bfdeb8badda40eeb2c8e7f597361d9",
		"streamref": "3-530-51168",
		"open": false,
		"details": {
		"purpose": "Stores the hex blob of raw exchange"
		},
		"subscribed": true,
		"synchronized": true,
		"items": 0,
		"confirmed": 0,
		"keys": 0,
		"publishers": 0
		}
	]
}


Sample code:


Subscribe node to a data stream


To subscribe a node to a data stream, use post /api/v1/subscribe and pass the stream name as a parameter.

The output will be null

Request body:

{
	"stream_name": "TEST_STREAM"
}


Response:

{
	"status": 200,
	"response": null
}


Sample code:


Unsubscribe node from a data stream


To unsubscribe a node to a data stream, use post /api/v1/unsubscribe and pass the stream name as a parameter.

The output will be null

Request body:

{
	"stream_name": "TEST_STREAM"
}


Response:

{
	"status": 200,
	"response": null
}


Sample code:


Write to a data stream


To write to a data stream, use post /api/v1/write_to_stream and pass the parameters as mentioned below in the request body.

Request body:

{
	"from_address": "17kpbJdha6vt8QjZz3nsctSx2qWK38idttfDV9",
	"key": "Invoice no. 443598724",
	"value": { 
		"issue_date": "08-11-2018",
		"value":"USD 44,500"
	},
	"stream": "TEST_STREAM"
}


Response:

{
	"status": 200,
	"response": "c3238398b4633d7a0be543e81b2f57cb1314f178fea2b71ae29d4423866d7fe9"
}


Sample code:


List stream items by key


To list stream items by key, use post /api/v1/list_trade_channel_items_by_key and pass 2 parameters - key and stream_name.

Request body:

{
	"key": "Invoice no. 443598724",
	"stream_name": "TEST_STREAM"
}


Response:

{
	"status": 200,
	"response": [
		{
			"publishers": "17kpbJdha6vt8QjZz3nsctSx2qWK38idttfDV9",
			"key": "Invoice no. 443598724",
			"data": "{"issue_date":"08-11-2018","value":"USD 44,500"}",
			"confirmations": 11,
			"blockhash": "075eaf3b5c8fd1063b18a0c02a6b67b106276aeff82bce22a4a809a199cf466e",
			"blockindex": 1,
			"blocktime": 1543234837,
			"txid": "c3238398b4633d7a0be543e81b2f57cb1314f178fea2b71ae29d4423866d7fe9",
			"vout": 0,
			"valid": true,
			"time": 1543234832,
			"timereceived": 1543234832
		}
	],
}


Sample code:


List stream items by publisher


To list stream items by publisher, use post /api/v1/list_trade_channel_items_by_publisher and pass 2 parameters - address and stream_name.

Request body:

{
	"address": "17kpbJdha6vt8QjZz3nsctSx2qWK38idttfDV9",
	"stream_name": "TEST_STREAM"
}


Response:

{
	"status": 200,
	"response": [
		{
			"publishers": "17kpbJdha6vt8QjZz3nsctSx2qWK38idttfDV9",
			"key": "Invoice no. 443598724",
			"data": "{"issue_date":"08-11-2018","value":"USD 44,500"}",
			"confirmations": 11,
			"blockhash": "075eaf3b5c8fd1063b18a0c02a6b67b106276aeff82bce22a4a809a199cf466e",
			"blockindex": 1,
			"blocktime": 1543234837,
			"txid": "c3238398b4633d7a0be543e81b2f57cb1314f178fea2b71ae29d4423866d7fe9",
			"vout": 0,
			"valid": true,
			"time": 1543234832,
			"timereceived": 1543234832
		}
	],
}


Sample code:


List keys in a specified stream


To list keys in a specified stream, use post /api/v1/list_stream_keys and pass 1 parameter - stream_name.

Request body:

{
	"stream_name": "TEST_STREAM"
}


Response:

{
	"status": 200,
	"response": [
		{
		"key": "Invoice no. 443598724"
		}
	]
}


Sample code:


Retrieve all data from a specified stream


To obtain all data from a specified stream, use post /api/v1/list_stream_items and pass 1 parameter - stream_name.

Request body:

{
	"stream_name": "TEST_STREAM"
}


Response:

{
"status": 200,
"response": [
		{
			"publishers": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"key": "1af89TzR7d7N3pqtKrfzQFxz9MYuNvpt2iFBmj",
			"data": "-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAk43Q5FlWcbnsU7Pbbxz1 cGVI3qtjOoRjyESCpKp/TTgiEr/6t8x6voo+WDOiiTTKD/jM/PGJkBh5bYiXwsDH wFqaEFa0wfvYTmGQxSBXwmuh45HdlWinryvXvZHlXnuCxZIPe7meW9FZN08QHRBL SNpMHBsfcVdPymRdfDwOJZb+GQPsO57RlIhJZ7SZ7KBtLaQu4xnrJcskRmj7vG28 zKixZFh5kuR0VJIdxPWwusURQJM6AUNkv9c1oIOPnkzXfOEYGoOqOtRSmXW5ifxy TjNcHyU7y9FABUbt+KPkZm+tngL91a3FQhT/qCgaARljQAiuL0MMNsc/N1wt6C+b XQIDAQAB -----END PUBLIC KEY-----",
			"confirmations": 2193,
			"blocktime": 1542716811,
			"txid": "8f76b080d29270ba34db89381d0594a03ab235e9c80fd3233f66f349f1e62fa4",
			"vout": 0,
			"valid": true,
			"time": 1542716799,
			"timereceived": 1542716799
		},
		{
			"publishers": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"key": "1C6ecGod2vqP85w8SRW1nquqn8HiynL9jjYzuP",
			"data": "-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoolY3G1f8y824OwJgLKV MXOVFRZbHoCYepwsRFF9VQ+tZVEgx1aT9JdjIq2IlixB35NSCiB+0beG4rPu10/X 8800+GRxV5o1NjxGXftNXpHxx9lLdvaj1KSkXs3XCUZ1ibXpx7WULQWzhybbnHUE cizZER3/WGeVeedZTURoYr4ZS+mu4Db7q39AWrtUoCPDKWntByUsoDltExm8voZW x8wAtiNONSyEL7xOZL8lLenP13vOT4xc1WG66nZI6p2W+GtzQxcXMil4/DJ912aC dycmEJWTC1OfR2qrKdMJZ73uRLUw712pDqVCB3IJkZoJAHosyL1bl95cpPUQnJzm wQIDAQAB -----END PUBLIC KEY-----",
			"confirmations": 1965,
			"blocktime": 1542802615,
			"txid": "2412d11977dbde02f30c2c38059d769a41c5b9b89f36bd92a53ec2568a89b1d7",
			"vout": 0,
			"valid": true,
			"time": 1542802604,
			"timereceived": 1542802604
		},
		{
			"publishers": "1aT3P8hqCK21x3EKyFKLzqLYdAnAqBALx3Gri3",
			"key": "1VtTz3kJvcGhnMBefhayNpzkRHqj5oudKUoXeD",
			"data": "-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsnNgnGjvlUYD26q0siHp zn6AtdXAw1m/QYm6Novu1UZaycN1sT5DG3A9H4HmStsxbF4mbyrJd+RZaih7C5Xz ASUYm0fphJTUx9KEbXH1zpYWxKhAVWnPOQ1kgQlP8uoAl8zupG9tnRTC5xyor1oc QfOJid2Suo2n6zymZlhyJsjcnVoVrG1TbgnkNCD/krZD/vOuEI3Sa8uHhOfv4YGI yQs/kqXaA4y/cRspx7GWPNt+Db6QHXXvCDnTTL80T4bp3Z7Y9IRn7VatyLXniNDI 1lzv82LXjrRIyAyHV+apbkapwGyH5Ir80rHjGNKigPdEngmWMAIdNJ3LjqyKshQj QQIDAQAB -----END PUBLIC KEY-----",
			"confirmations": 1888,
			"blocktime": 1542884017,
			"txid": "33555a6ae4a76f308c896ae1ecb766935b6322ee96a6383ef4eee6d8a230de6b",
			"vout": 0,
			"valid": true,
			"time": 1542884010,
			"timereceived": 1542884010
		}
	]
}


Sample code:


Smart Asset Lifecycle Management

A blockchain smart asset can be the digital representation of a real-world asset (e.g. gold, equity shares, fiat currency, stressed asset) or an asset in itself (e.g. bitcoin and other crypto-currencies). The blockchain removes the characteristic of infinite reproducibility from a digital asset. It confirms that each unit of value was transferred only once, solving the long-standing problem of double spending. A blockchain can assign title rights because it provides a record that compels offer and acceptance.

Create a new asset


To create a new smart asset, use post /api/v1/create_token.

Note:

  • This may take upto 30 seconds.
  • from_address is the entity that creates the asset. It must have send, receive and issue permissions. It must also have permissions to write to the ASSET_DATA_MASTERLIST
  • to_address is the entity that receives the newly created asset. It must have receive permission and ideally also send permission.
  • The from_address and to_address can be the same.
  • unit refers to the minimum divisible quantity of the asset.
  • asset refers to the name of the asset.
  • quantity refers to the initial quantity of the asset.
  • details refers to any details about the asset.
  • Setting open to true will create an open asset - additional units of the asset CAN be issued in the future.
  • Setting open to false will create a closed asset - additional units of the asset CANNOT be issued in the future.


Request body:

{
	"from_address": "1K2MYAXp1tiMEKw2VKMrzy8X9peZFrrUbvZnXK",
	"to_address": "4NM46pESGpnvCn8pJmVZpuFepaeUkwKF3YecSM",
	"asset": {
		"name": "SILVER-tokens-series-A",
		"open": false
	},
	"unit": 1,
	"quantity": 19500,
	"details": "Backed by silver jewellery held in Lot A at Zimblia office" 
}


Output:

  • the txid of the transaction in which the asset was created.
  • the reference number of the asset.


Response:

{
	"status": 200,
	"tx_id": "00897558db1f7d2b4682ca79afd1830d5066266bc0118bbe87c7e2ff3a9cc5e1",
	"asset_ref": "1074-267-61526",
	"description": {
		"details": "Backed by silver jewellery held in Lot A at Zimblia office"
	}
}


Sample code:


Create additional units of an open asset


To create additional units of an open asset, use post /api/v1/create_more_token.

Note:

  • This may take upto 30 seconds.
  • from_address is the entity that creates the asset. It must have send permission.
  • to_address is the entity that receives the newly created asset. It must have receive permission.
  • The from_address and to_address can be the same.
  • asset refers to the name of the asset.
  • quantity refers to the initial quantity of the asset.

Output is the id of the transaction in which the additional units were created.

Request body:

{
	"from_address": "1K2MYAXp1tiMEKw2VKMrzy8X9peZFrrUbvZnXK",
	"to_address": "4NM46pESGpnvCn8pJmVZpuFepaeUkwKF3YecSM",
	"asset_name": "SILVER-tokens-series-B",
	"quantity": 5000
}


Output is the txid of the transaction in which more units of the asset were created.

Response:

{
	"status": 200,
	"tx_id": "c749efc4cca56b72749e8e2d0acf7bf6282383255482894c578e4c82869fbc4f"
}


Sample code:


Details of a specified asset


To get details of a specific asset, use post /api/v1/asset_details and pass the asset name or reference id as a parameter.

Request body:

{
	"asset_name": "AUTH-tokens-series-A"
}


Output:

  • the txid of the transaction in which the asset was created.
  • the reference number of the asset.


Response:

{
	"status": 200,
	"response": 
	[
		{
			"name": "AUTH-tokens-series-A",
			"issuetxid": "d7621cb45b226a4bbf86bde4eb0b7fe700ebfc000f8bb12450362746777dbe44",
			"assetref": "324-267-25303",
			"multiple": 1,
			"units": 1,
			"open": true,
			"details": {
				"details": "These are AUTH tokens"
			},
			"issueqty": 45350,
			"issueraw": 45350,
			"subscribed": true,
			"synchronized": true,
			"transactions": 2,
			"confirmed": 2,
			"issues": 
			[
				{
					"txid": "d7621cb45b226a4bbf86bde4eb0b7fe700ebfc000f8bb12450362746777dbe44",
					"qty": 45000,
					"raw": 45000,
					"details": {
						"details": "These are AUTH tokens"
					},
					"issuers": [
						"1N9VtvZvP3rsw5Rf4Qpi12TWBaDoEwM2BAEsv2"
					]
				},
				{
					"txid": "0ac10e7cc5d1a3bdd959f74034fabaae7e40ec5e4515aba4c57002e6e50b9736",
					"qty": 350,
					"raw": 350,
					"details": {},
					"issuers": [
						"1N9VtvZvP3rsw5Rf4Qpi12TWBaDoEwM2BAEsv2"
					]
				}
			]
		}
	]
}


Sample code:


Assets held by specified entities


Use post /api/v1/assets_held_by_entity to get details of Assets held by specified entities.

Single address input

Request body:

{
	"primechain_address": "4NM46pESGpnvCn8pJmVZpuFepaeUkwKF3YecSM"
}


Response:

{
	"status": 200,
	"response": {
		"4NM46pESGpnvCn8pJmVZpuFepaeUkwKF3YecSM": [
			{
				"name": "SILVER-tokens-series-A",
				"assetref": "1074-267-61526",
				"qty": 19500
			},
			{
				"name": "SILVER-tokens-series-B",
				"assetref": "1086-266-919",
				"qty": 33500
			}
		],
		"total": [
			{
				"name": "SILVER-tokens-series-A",
				"assetref": "1074-267-61526",
				"qty": 19500
			},
			{
				"name": "SILVER-tokens-series-B",
				"assetref": "1086-266-919",
				"qty": 33500
			}
		]
	}
}


Multiple addresses input

Request body:

{
	"primechain_address": [
		"1N9VtvZvP3rsw5Rf4Qpi12TWBaDoEwM2BAEsv2",
		"16H6WdDR7LpHzVeEkdTiE6dNiPHBniPtnxTYdd"
	]
}


Response:

{
	"status": 200,
	"response": {
		"1N9VtvZvP3rsw5Rf4Qpi12TWBaDoEwM2BAEsv2": [
			{
				"name": "AUTH-tokens-series-A",
				"assetref": "324-267-25303",
				"qty": 45350
			},
			{
				"name": "GOLD-tokens-series-A",
				"assetref": "301-267-14695",
				"qty": 19460
			}
		],
		"16H6WdDR7LpHzVeEkdTiE6dNiPHBniPtnxTYdd": [
			{
				"name": "GOLD-tokens-series-A",
				"assetref": "301-267-14695",
				"qty": 40
			}
		],
		"total": [
			{
				"name": "AUTH-tokens-series-A",
				"assetref": "324-267-25303",
				"qty": 45350
			},
			{
				"name": "GOLD-tokens-series-A",
				"assetref": "301-267-14695",
				"qty": 19500
			}
		]
	}
}


Sample code:


Transfer asset when private key is in the node


To send assets when the sender's private key is in the node, use post /api/v1/send_asset and pass 5 parameters -

  • Sender's address
  • Receiver's address
  • Asset name or reference
  • Asset quantity
  • Details of the transaction

The output is the id of the transaction in which the asset was transferred.


Request body:

{
	"from_address": "1K2MYAXp1tiMEKw2VKMrzy8X9peZFrrUbvZnXK",
	"to_address": "4NM46pESGpnvCn8pJmVZpuFepaeUkwKF3YecSM",
	"asset_name": "SILVER-tokens-series-A",
	"quantity": 12,
	"details": "These are the details of this transfer"
}


Response:

{
	"status": 200,
	"tx_id": "79e44ffa6e8b611ee7750f8a41bb16e44e628c9ef48c4c55ba15314a2c574428"
}


Sample code:


Transfer asset from multisig address


To send assets from a multisig address, use post /api/v1/transfer_multisign_asset and pass 5 parameters -

  • Sender's address
  • Receiver's address
  • Asset name or reference
  • Asset quantity
  • Senders' private keys (of minimum required signers)

The output is the id of the transaction in which the asset was transferred.


Request body:

{
	"from_address": "4NM46pESGpnvCn8pJmVZpuFepaeUkwKF3YecSM",
	"to_address": "1GkxHWs76J2SbyZtq68NUuCMuBc48eERkcukFN",
	"asset_name": "SILVER-tokens-series-A",
	"quantity": 175,
	"senders_private_key": [
		"VGEnfWgmCLCMjU2ao9tAp3JxX9eK2ahMMiUevqLUN1A9HwFPA5hB5sDH",
		"VHRLz6v1VypfTWpqNxAnhVhxNFG77K2XpVgtdNf3PwypovVX14TZrNjA"
	]
}


Response:

{
	"status": 200,
	"tx_id": "3f48baa90aba1b01e2fa857a965170a904e0ec657745c5b501f05d7bcad37176"
}


Sample code:


Transfer asset when private key is not in the node


To send assets when the sender's private key is not in the node, use post /api/v1/transfer_asset and pass 5 parameters -

  • Sender's address
  • Receiver's address
  • Asset name or reference
  • Asset quantity
  • Senders' private key

The output is the id of the transaction in which the asset was transferred.


Request body:

{
	"senders_address": "1GkxHWs76J2SbyZtq68NUuCMuBc48eERkcukFN",
	"receivers_address": "1K2MYAXp1tiMEKw2VKMrzy8X9peZFrrUbvZnXK",
	"asset_name": "SILVER-tokens-series-A",
	"asset_quantity": 8,
	"senders_private_key": "V9ckYDSE8TX7T1Mzm9nGbBteC5kLBFdFZdFYWZp6qcLyPnjhcsszZScc"
}


Response:

{
	"status": 200,
	"tx_id": "42dc57c7068b84bf126a6ed340f3d8696dbbd7b417ff314609e8ed041d2755ad"
}


Sample code:


Transactions by a specified entity


To list information about the transactions related to an address in this node's wallet, including how they affected that address's balance, use post /api/v1/address_transaction and pass the address as a parameter.

Request body:

{
	"primechain_address": "1GkxHWs76J2SbyZtq68NUuCMuBc48eERkcukFN"
}


Response:

{
	"status": 200,
	"address_transaction": [
		{
			"balance": {
				"amount": 0,
				"assets": [
					{
					"name": "SILVER-tokens-series-A",
					"assetref": "1074-267-61526",
					"qty": 175
					}
				]
			},
			"myaddresses": [
				"1GkxHWs76J2SbyZtq68NUuCMuBc48eERkcukFN"
			],
			"addresses": [
				"4NM46pESGpnvCn8pJmVZpuFepaeUkwKF3YecSM"
			],
			"permissions": [],
			"items": [],
			"data": [],
			"confirmations": 30,
			"blockhash": "02a120250ab453e59fee1fd6e5bfcb7bc4e0ed58ac9c333770f8c1edafe4e793",
			"blockindex": 1,
			"blocktime": 1546418902,
			"txid": "3f48baa90aba1b01e2fa857a965170a904e0ec657745c5b501f05d7bcad37176",
			"valid": true,
			"time": 1546418892,
			"timereceived": 1546418892
		},
		{
			"balance": {
				"amount": 0,
				"assets": [
					{
					"name": "SILVER-tokens-series-A",
					"assetref": "1074-267-61526",
					"qty": -8
					}
				]
			},
			"myaddresses": [
				"1GkxHWs76J2SbyZtq68NUuCMuBc48eERkcukFN"
			],
			"addresses": [
				"1K2MYAXp1tiMEKw2VKMrzy8X9peZFrrUbvZnXK"
			],
			"permissions": [],
			"items": [],
			"data": [],
			"confirmations": 6,
			"blockhash": "08907aeee46289a6db18c96371e309030b96c3b55f2f2c9f98cbcf3232d48863",
			"blockindex": 1,
			"blocktime": 1546419624,
			"txid": "42dc57c7068b84bf126a6ed340f3d8696dbbd7b417ff314609e8ed041d2755ad",
			"valid": true,
			"time": 1546419613,
			"timereceived": 1546419613
		}
	]
}


Sample code:


Offer management

Create a public offer


To create an offer, use post /api/v1/create_public_offer and pass these parameters:

  • address of the entity making the offer - primechain_address
  • name and quantity of asset asked for - ask_asset
  • name and quantity of asset offerred in return - offer_asset


The following is stored in the OFFER_DETAIL_STREAM
  1. primechain_address of the offer creator
  2. name of asset asked for
  3. name of asset offerred
  4. quantity of asset asked for
  5. quantity of asset offerred
  6. offer hex blob


Request body:

{
	"primechain_address": "16H6WdDR7LpHzVeEkdTiE6dNiPHBniPtnxTYdd",
	"ask_asset": {
		"AUTH-tokens-series-A": 4
	},
	"offer_asset": {
		"GOLD-tokens-series-A": 2
	}
}


The output is the id and vout of the transaction in which the offer data is stored in the blockchain.

Response:

{
	"status": 200,
	"response": {
		"offer_txid": "d8e32370ecd43ca8c22191b7a206db9b91144d040f0d20492df02cb544e0e4f8",
		"offer_vout": 0
	}
}


Sample code:


Get list of open public offers


To get a list of open public offers made by an address,use post /api/v1/get_open_offer and pass the address as a parameter.

Request body:

{
	"primechain_address": "16H6WdDR7LpHzVeEkdTiE6dNiPHBniPtnxTYdd"
}


The output is the id and vout of the transaction in which the offer data is stored in the blockchain.

Response:

{
	"status": 200,
	"response": [
		{
			"primechain_address": "16H6WdDR7LpHzVeEkdTiE6dNiPHBniPtnxTYdd",
			"ask_asset": "AUTH-tokens-series-A",
			"offer_asset": "GOLD-tokens-series-A",
			"bid_amount": 4,
			"offer_amount": 2,
			"txid": "8d09db2c2a7f05c54adfd1c5dcf343b9980ff52c61fa17b24bac6e12ff9dd894",
			"vout": 0
		},
		{
			"primechain_address": "16H6WdDR7LpHzVeEkdTiE6dNiPHBniPtnxTYdd",
			"ask_asset": "AUTH-tokens-series-A",
			"offer_asset": "GOLD-tokens-series-A",
			"bid_amount": 4,
			"offer_amount": 2,
			"txid": "65b6293b60cac5bec78e346486724f150103e55c9267b9ec86405590224fbe58",
			"vout": 0,
			"offer_blob": "010000000158be4f2290554086ecb967925ce50301154f728664348ec7bec5ca603b29b665000000006a473044022018726f00fad05632a1f2d72718d4e276c018a5196c47dc936167c7d1cedcb544022062678becdca71459438983490ef400e6a974d7597fe56135cfb3b0c54e7e6e28832103ab7548d8c3148110f595453ac491dfe45d271c92b88d0cfdd26b41eaa7bfbaa0ffffffff0100000000000000003776a914270c3ebee9d184df26275424af915236f51afddf88ac1c73706b71e77f0bebe4bd86bf4b6a225bb41c62d704000000000000007500000000"
		}
	]
}


Sample code:


Read an offer


To interpret an offer, use post /api/v1/read_offer and pass the hex blob:

Request body:

{
	"offer_blob": "0100000001f8e4e044b52cf02d49200d0f044d14919bdb06a2b79121c2a83cd4ec7023e3d800000000694630430220024cd963ec869126c15611ae168f39f4bfdcd507a8d7e3738d0792e5f9ae09b6021f236f20aca9966fde2fd7ec9c0046585d42901cff7d7e3676729a4e0dc69dbd832103ab7548d8c3148110f595453ac491dfe45d271c92b88d0cfdd26b41eaa7bfbaa0ffffffff0100000000000000003776a914270c3ebee9d184df26275424af915236f51afddf88ac1c73706b71e77f0bebe4bd86bf4b6a225bb41c62d704000000000000007500000000"
}


Response:

{
	"status": 200,
	"response": {
		"offer": {
			"amount": 0,
			"assets": [
				{
					"name": "GOLD-tokens-series-A",
					"assetref": "301-267-14695",
					"qty": 2
				}
			],
		},
		"ask": {
			"amount": 0,
			"assets": [
				{
					"name": "AUTH-tokens-series-A",
					"assetref": "324-267-25303",
					"qty": 4
				}
			]
		},
		"requiredfee": 0,
		"candisable": true,
		"cancomplete": true,
		"complete": false
	}
}


Sample code:


Accept an offer


To accept an offer, use post /api/v1/accept_offer and pass 2 parameters -

  • primechain_address of the acceptor
  • offer_blob relating to the offer


Request body:

{
	"primechain_address": "1CbfDWDYN8A7i4zZisEzfkLwRcQUem3PaUin9p",
	"offer_blob": "0100000001f8e4e044b52cf02d49200d0f044d14919bdb06a2b79121c2a83cd4ec7023e3d800000000694630430220024cd963ec869126c15611ae168f39f4bfdcd507a8d7e3738d0792e5f9ae09b6021f236f20aca9966fde2fd7ec9c0046585d42901cff7d7e3676729a4e0dc69dbd832103ab7548d8c3148110f595453ac491dfe45d271c92b88d0cfdd26b41eaa7bfbaa0ffffffff0100000000000000003776a914270c3ebee9d184df26275424af915236f51afddf88ac1c73706b71e77f0bebe4bd86bf4b6a225bb41c62d704000000000000007500000000"
}


Response:

{
	"status": 200,
	"response": "932b8b016c5465981c7d68dc1ec4d6ce2157416c821a05699fbb1a4796b03a47"
}


Sample code:


Cancel a public offer


To cancel an offer, use post /api/v1/cancel_public_offer and pass the offerer's address and txid of the offer as a parameter.

Request body:

{
	"primechain_address": "16H6WdDR7LpHzVeEkdTiE6dNiPHBniPtnxTYdd",
	"tx_id": "d8e32370ecd43ca8c22191b7a206db9b91144d040f0d20492df02cb544e0e4f8"
}


Response:

{
	"status": 200,
	"response": true
}


Sample code:


Create a targeted offer


To create an offer, use post /api/v1/create_targeted_offer and pass these parameters:

  • address of the entity making the offer - primechain_address
  • name and quantity of asset asked for - ask_asset
  • name and quantity of asset offerred in return - offer_asset


Request body:

{
	"from_address": "16H6WdDR7LpHzVeEkdTiE6dNiPHBniPtnxTYdd",
	"to_address": "1CbfDWDYN8A7i4zZisEzfkLwRcQUem3PaUin9p",
	"ask_asset": {
		"AUTH-tokens-series-A": 4
	},
	"offer_asset": {
		"GOLD-tokens-series-A": 2
	}
}


The output is the transaction id and the offer blob of the offer details.

Response:

{
	"status": 200,
	"response": {
		"offer_blob": "0100000001ff5eec083a418dc55a8ce638b0953c5bb22750b5e75407f07f96ca99a130489d000000006a47304402206774afd0964167b47d97a36135f94aa46deb39aba25359d6c898cf3d31a5c184022041753eadc1f0e1096d2f6e95765be7ea27725a6488dbb18940b1420839de8f15832103ab7548d8c3148110f595453ac491dfe45d271c92b88d0cfdd26b41eaa7bfbaa0ffffffff0100000000000000003776a914270c3ebee9d184df26275424af915236f51afddf88ac1c73706b71e77f0bebe4bd86bf4b6a225bb41c62d704000000000000007500000000",
		"offer_txid": "9d4830a199ca967ff00754e7b55027b25b3c95b038e68c5ac58d413a08ec5eff",
		"offer_vout": 0
	}
}


Sample code:


Reject a targeted offer


To reject an offer, use post /api/v1/reject_targeted_offer and pass the offeree address and txid of the offer as a parameter.

Request body:

{
	"primechain_address": "1CbfDWDYN8A7i4zZisEzfkLwRcQUem3PaUin9p",
	"tx_id": "9d4830a199ca967ff00754e7b55027b25b3c95b038e68c5ac58d413a08ec5eff"
}


Response:

{
	"status": 200,
	"response": true
}


Sample code:


Encrypted data storage

Introduction


For an overview of the digital / electronic signature process, see this.

Glossary of terms

  • AAD: Additional Authenticated Data
  • AES: Advanced Encryption Standard.
  • Authentication Tag (Tag): A cryptographic checksum on data that is designed to reveal both accidental errors and the intentional modification of the data.
  • GCM: Galois/Counter Mode
  • Initialization Vector: A nonce that is associated with an invocation of authenticated encryption on a particular plaintext and AAD.

For more information, see NIST Special Publication 800-38D


Sign, encrypt and store data in the blockchain


To encrypt data and store the encrypted data in the blockchain, use post /api/v1/encrypt_sign_store_data and pass 2 parameters:

  • the data
  • the primechain address of the signing entity

This is what happens:

Step 1: Hash computation
The SHA-512 hash of the data is computed.

Step 2: Signing
The hash is signed using the private key of the signing entity (using ECDSA).

Step 3: Storing the signature
The following are published to the DATA_SIGNATURE_MASTERLIST stream:

  • the digital signature
  • the hash
  • the primechain address of the signing entity

Step 4: Encrypting the data
The data is encrypted using the AES (Advanced Encryption Standard) algorithm and the following are generated:

  • the encrypted version of the data
  • the AES password
  • the Initialization Vector (IV)
  • the Authentication Tag (tag)

Step 5: Storing the encrypted data
The encrypted data and the tag are published to the DATA_MASTERLIST stream.

Step 6: Output
The following is the output:

  • the id of the transaction in which the encrypted data and tag were published to the DATA_MASTERLIST stream
  • the id of the transaction in which the digital signature, hash and the signer's primechain address were published to the DATA_SIGNATURE_MASTERLIST stream
  • The AES password
  • The Initialization Vector (IV)


Request body:

{
	"primechain_address": "1N9VtvZvP3rsw5Rf4Qpi12TWBaDoEwM2BAEsv2",
	"data": {
		"name": "Scarlett Johansson",
		"email": "scarlett@example.com",
		"cell": ":1234567890"
	}
}


Response:

{
"status": 200,
"response": {
		"tx_id_enc_data": "a8441a8e8fe52c6f84941fd1f08f774ecbf0dc9edf9fd18e9f9d20f1d2945940",
		"tx_id_signature": "8f15a1b3bc4cbeeae89ea28e77982ac7baa04c45870d9d40086b799ad795487f",
		"signature": "H523zhPwR1gdPn2R0/JlfTJLWB5HaII96vJcDx4qy8f2StF1AE6Qfft8lqE2IoDd2czj5cW8i9ZJLaWXu7KkEyE=",
		"aes_password": "5M1qnsYeRmSvlwNtZ8oJiHC0g9ucVrgc",
		"aes_iv": "zNc59qnYapAw"
	}
}


Sample code:


Decrypt, verify and retrieve data from the blockchain


To retrieve data from the blockchain and decrypt it, use post /api/v1/decrypt_download_data and pass these values:

  • the id of the transaction in which the encrypted data and tag were published to the DATA_MASTERLIST stream
  • the id of the transaction in which the digital signature, hash and the signer's primechain address were published to the DATA_SIGNSTURE_MASTERLIST stream
  • The AES password
  • The Initialization Vector (IV)

This is what happens:

Step 1: Retrieval of signing data
The digital signature, hash and the primechain address of the signing entity are retrieved from the DATA_SIGNSTURE_MASTERLIST stream.

Step 2: Retrieval of encrypted data
The encrypted data and tag are retrieved from the DATA_MASTERLIST stream.

Step 3: Decryption
The encrypted data is decrypted.

Step 4: Verification
The digital signature is verified

Step 5: Output
The output will be the data and the details of the signer.


Request body:

{
	"tx_id_enc_data": "a8441a8e8fe52c6f84941fd1f08f774ecbf0dc9edf9fd18e9f9d20f1d2945940",
	"tx_id_signature": "8f15a1b3bc4cbeeae89ea28e77982ac7baa04c45870d9d40086b799ad795487f",
	"aes_password": "5M1qnsYeRmSvlwNtZ8oJiHC0g9ucVrgc",
	"aes_iv": "zNc59qnYapAw"
}


Response:

{
"status": 200,
"response": {
		"data": {
			"name": "Scarlett Johansson",
			"email": "scarlett@example.com",
			"cell": ":1234567890"
		},
		"signer_detail": {
			"name": "Noodle Bank Official Signer",
			"primechain_address": "1N9VtvZvP3rsw5Rf4Qpi12TWBaDoEwM2BAEsv2"
		},
		"signature_status": true
	}
}


Sample code:


Sign, encrypt and store a file in the blockchain


To encrypt a file and store the encrypted file in the blockchain, use post /api/v1/encrypt_sign_store_file and pass 2 parameters:

  • the file data
  • the primechain address of the signing entity

This is what happens:

Step 1: Hash computation
The SHA-512 hash of the file is computed.

Step 2: Signing
The hash is signed using the private key of the signing entity (using ECDSA).

Step 3: Storing the signature
The following are published to the FILE_SIGNATURE_MASTERLIST stream:

  • the digital signature
  • the hash
  • the primechain address of the signing entity

Step 4: Encrypting the file
The file is encrypted using the AES (Advanced Encryption Standard) algorithm and the following are generated:

  • the encrypted version of the file
  • the AES password
  • the Initialization Vector (IV)
  • the Authentication Tag (tag)

Step 5: Storing the encrypted file
The encrypted file and the tag are published to the FILE_MASTERLIST stream.

Step 6: Output
The following is the output:

  • the id of the transaction in which the encrypted file and tag were published to the FILE_MASTERLIST stream
  • the id of the transaction in which the digital signature, hash and the signer's primechain address were published to the FILE_SIGNATURE_MASTERLIST stream
  • The AES password
  • The Initialization Vector (IV)


Request body:

{
	"primechain_address": "1N9VtvZvP3rsw5Rf4Qpi12TWBaDoEwM2BAEsv2",
	"file":"<your file>"
}


Response:

{
"status": 200,
"response": {
		"tx_id_enc_file":"a8441a8e8fe52c6f84941fd1f08f774ecbf0dc9edf9fd18e9f9d20f1d2945940".
		"tx_id_signature": "8f15a1b3bc4cbeeae89ea28e77982ac7baa04c45870d9d40086b799ad795487f",
		"signature": "H523zhPwR1gdPn2R0/JlfTJLWB5HaII96vJcDx4qy8f2StF1AE6Qfft8lqE2IoDd2czj5cW8i9ZJLaWXu7KkEyE=",
		"aes_password": "5M1qnsYeRmSvlwNtZ8oJiHC0g9ucVrgc",
		"aes_iv": "zNc59qnYapAw"
	}
}


Sample code:


Decrypt, verify and retrieve a file from the blockchain


To retrieve a file from the blockchain and decrypt it, use post /api/v1/decrypt_download_file and pass these values:

  • the id of the transaction in which the encrypted file and tag were published to the DATA_MASTERLIST stream
  • the id of the transaction in which the digital signature, hash and the signer's primechain address were published to the DATA_SIGNSTURE_MASTERLIST stream
  • The AES password
  • The Initialization Vector (IV)

This is what happens:

Step 1: Retrieval of signing data
The digital signature, hash and the primechain address of the signing entity are retrieved from the DATA_SIGNSTURE_MASTERLIST stream.

Step 2: Retrieval of encrypted file
The encrypted file and tag are retrieved from the DATA_MASTERLIST stream.

Step 3: Decryption
The encrypted file is decrypted.

Step 4: Verification
The digital signature is verified

Step 5: Output
The output will be the file and the details of the signer.


Request body:

{
	"tx_id_enc_file": "a8441a8e8fe52c6f84941fd1f08f774ecbf0dc9edf9fd18e9f9d20f1d2945940",
	"tx_id_signature": "8f15a1b3bc4cbeeae89ea28e77982ac7baa04c45870d9d40086b799ad795487f",
	"aes_password": "5M1qnsYeRmSvlwNtZ8oJiHC0g9ucVrgc",
	"aes_iv": "zNc59qnYapAw"
}


Response:

{
"status": 200,
"response": {
		"file": "<file data>",
		"signer_detail": {
			"name": "Noodle Bank Official Signer",
			"primechain_address": "1N9VtvZvP3rsw5Rf4Qpi12TWBaDoEwM2BAEsv2"
		},
		"signature_status": true
	}
}


Sample code: