♠
documentation
StarchChain API Reference
The StarchChain API is built using common web design rules (REST). It features clear, predictable web addresses and accepts data sent through basic web forms. It always sends information back to you in the easy-to-read JSON format, and it uses standard internet error messages to let you know if your request succeeded or failed.
Read these docs in Markdown: docs.md
BASE URL: https://api.starch.one
Endpoints
Last Blockchain Hash
Endpoint: /blockchain/last_hash GET
Example in Python:
import requests, json
response = requests.get("https://api.starch.one/blockchain/last_hash")
json_response = json.loads(response.text)
Returns:
{"hash": "ad85eccd13124a45587d38c1763ee6c45f0e6b28bc95a98758905da0d6299eb2"}
Block Creation
Uses: /blockchain/last_hash GET
Example in Python:
import requests, json
from hashlib import sha256
response = requests.get("https://api.starch.one/blockchain/last_hash")
json_response = json.loads(response.text)
last_hash = json_response["hash"]
miner_id = "00000000"
color = "#FEE600"
block_string = f'{last_hash} {miner_id} {color}'
new_hash = sha256(block_string.encode()).hexdigest()
block = {"hash": new_hash, "miner_id": miner_id, "color": color}
Returns:
{
"hash": "c175b09fc5ec15891522a44d0988699d90c0280e2d7f31846234efadc939411b",
"miner_id": "00000000",
"color": "#FEE600"
}
Submit Blocks
Endpoint: /submit_blocks POST
Example in Python:
import requests, json
data = {"blocks": blocks}
response = requests.post("https://api.starch.one/submit_blocks", json=data)
Returns:
{
"00000000": {
"block": "pending"
}
}
Check For Pending Blocks
Endpoint: /pending_blocks GET
Example in Python:
import requests, json
response = requests.get("https://api.starch.one/pending_blocks")
json_response = json.loads(response.text)
Returns:
{"blocks": [
{
"hash": "c175b09fc5ec15891522a44d0988699d90c0280e2d7f31846234efadc939411b",
"miner_id": "00000000",
"color": "#FEE600"
}
]}
Check If A Miner's Has a Pending Block
Endpoint: /pending_blocks/{miner_id} GET
Example in Python:
import requests, json
miner_id = "00000000"
response = requests.get(f"https://api.starch.one/pending_blocks/{miner_id}")
json_response = json.loads(response.text)
Returns:
{
"hash": "c175b09fc5ec15891522a44d0988699d90c0280e2d7f31846234efadc939411b",
"miner_id": "00000000",
"color": "#FEE600"
}
Pending Block Size
Endpoint: /pending_blocks/size GET
Example in Python:
import requests, json
response = requests.get("https://api.starch.one/pending_blocks/size")
json_response = json.loads(response.text)
Returns:
{"block_count": 785}
Get Miner Snapshot
Endpoint: /miner/{miner_id} GET
Example in Python:
import requests, json
miner_id = "00000000"
response = requests.get(f"https://api.starch.one/miner/{miner_id}")
json_response = json.loads(response.text)
Returns:
{
"team": "FEE600",
"pool": "4free",
"block_id": 690518,
"balance": 271096922,
"blocks": 1110,
"online": 785,
"profile": {
"name": "Abstract Potato",
"description": "I eat potato, I become potato."
},
"leaderboard": {
"week": {
"blocks": 3,
"rank": 481
}
},
"attendance": [690518, 690517, 690516, 690515, 690514, 690513, 690512]
}
Data Attributes:
| Attribute | Data Type | Description |
|---|---|---|
| Team (Optional) | String | The Company ID this Miner is employed with. |
| Pool (Optional) | String | The Cardano Stake Pool this Miner's wallet is delegated to. |
| Block ID | Integer | Current Blockchain tip. |
| Balance | Integer | STRCH Token balance. |
| Blocks | Integer | Total mined blocks by this Miner. |
| Online | Integer | Online miners in previous block |
| Profile (Optional) | Map | Miner name and Description |
| Leaderboard (Optional) | Map | Mining rank (Weekly/Overall) |
| Attendance | Array | Block attendance from last 588 blocks |
Get Last Block Header
Endpoint: /blockchain/last_block
Example in Python:
import requests, json
response = requests.get("https://api.starch.one/blockchain/last_block")
json_response = json.loads(response.text)
Returns:
{
"block_id": 690530,
"previous_hash": "46bae1604de0bccd87ddd56721665037977675f010aee119c0b2ef45addd9022",
"hash": "dec828a740b4d849bb6eb2a43335e58018b6345318c19be7a0329bfaf0d1289c",
"miner_id": "T64S49TU",
"color": "#641a46"
}
Get Block By ID
Endpoint: /blockchain/id/{block_id}
Example in Python:
import requests, json
block_id = 690530
response = requests.get(f"https://api.starch.one/blockchain/id/{block_id}")
json_response = json.loads(response.text)
Returns:
{
"block_id": 690530,
"hash": "dec828a740b4d849bb6eb2a43335e58018b6345318c19be7a0329bfaf0d1289c",
"previous_hash": "46bae1604de0bccd87ddd56721665037977675f010aee119c0b2ef45addd9022",
"miner_id": "T64S49TU",
"color": "#641a46",
"reward": 6250000,
"team_config": "ed9f0950275b0833ee149950e5009493f6779a945928246fc33bdf17d67f7f54",
"vrf": "ca24bbde6758e0d1231debfbc80b98146ea95512556616e277c5361976af6df9",
"timestamp": 1782324997,
"era": "au_gratin",
"version": 2,
"stake_reward": {
"amount": 2322027,
"epoch": 639,
"pool": "drmz"
},
"distribution": [
{
"amount": 8572027,
"to": "B8C086"
}
],
"attendance": [...]
}
Data Attributes:
| Attribute | Data Type | Description |
|---|---|---|
| Block ID | Integer | This Block's height. |
| Hash | String | This Block's hash. |
| Previous Hash | String | The previous block's hash. |
| Miner ID | String | The miner of this block. |
| Color | String | Hex color block nonce. |
| Reward | Integer | STRCH mining reward. |
| Team Config | String | Signature ID for the Company Config. |
| VRF | String | VRF hash for Proof of Attendance protocol. |
| Timestamp | Integer | UTC timestamp in Milliseconds. |
| Era | String | Current blockchain era. |
| Version | Integer | Block version. |
| Stake Reward | Map | Starch Pool delegation reward. |
| Distribution | List | How rewards were distributed based on Company Config. |
| Attendance | List | Miners who participated in this block. |
Code Examples
Block creation & Submission
Uses /blockchain/last_hash GET and /submit_blocks POST
Example in Python:
import requests, json
from hashlib import sha256
def get_last_hash():
response = requests.get("https://api.starch.one/blockchain/last_hash")
json_response = json.loads(response.text)
return json_response
def create_block(last_hash: str, miner_id: str, color: str):
block_string = f'{last_hash} {miner_id} {color}'
new_hash = sha256(block_string.encode()).hexdigest()
return {"hash": new_hash, "miner_id": miner_id, "color": color}
def submit_block(block: dict):
blocks = {"blocks": [block]}
response = requests.post("https://api.starch.one/submit_blocks", json=blocks)
json_response = json.loads(response.text)
return json_response
last_hash = get_last_hash()["hash"]
miner_id = "00000000"
color = "#FEE600"
block = create_block(last_hash, miner_id, color)
submit_block(block)
Returns:
{
"00000000": {
"block": "pending"
}
}