masternode.space API v1.0

For the scripts that look after your masternodes: see each one and what the network says of it, add one with your own keys, renew from the balance, revive a banned one, delete. Everything the dashboard lets you do with them, by the same rules.

Getting started

Make a key in Settings → API keys. A read key can look; a write key can also add, renew, revive and delete masternodes, paying from your balance - keep it as you would your password. Up to 5 keys an account, each named for what uses it.

A key is shown when it is made. After that it is shown again only to your password, and it can be made anew, which stops the old one at once. Every key made, or made anew, is announced to you - by mail, and on Telegram if your account is linked to it. Resetting a forgotten password deletes every key on the account; changing it in Settings does not.

Send it with every request:

Authorization: Bearer mns_...

Every path below starts at https://masternode.space/api/v1.0. Bodies are JSON, sent with Content-Type: application/json; a GET or a DELETE has none.

Answers and errors

What was asked for comes in response, with a 2xx status:

{ "response": { ... } }

A refusal comes in error, with the HTTP status that fits it. Branch on code: it stays as it is. message is for a person to read and may be reworded. Some errors carry more, such as field or retry_after - each is in the list of codes.

{
  "error": {
    "code": "balance_short",
    "message": "Your balance does not cover this. Top it up and send the request again.",
    "price": "9.40000000",
    "balance": "3.10000000",
    "short": "6.30000000"
  }
}

Times: Unix seconds, UTC.
Amounts: Strings of decimals, such as "150.00000000", in the coin unless the name ends in _usd - a float would round them. Send them the same way.
Query strings: None. A URL with one is refused; everything goes in the path or the body.

Limits

Requests: 60 a minute from one IP address, with bursts of up to 30. Past that, 429 too_many_requests.
Network lookups: Adding a masternode, a new operator key and a revival each ask the coin's network about it. An account has 500 lookups an hour, shared with the site; past that, 429 too_many_lookups with retry_after.
Masternodes listed: 500, newest first; truncated says when there are more.

GET /account read key

Balances and daily cost

Your balance in each coin, and what the masternodes that renew from it cost per day.

covered_until is when the balance stops paying for the renewals, worked through in the order they fall, at this moment's rate. Rates move, so it is an estimate - check it again rather than planning a month ahead on it.

Answer

user_idinteger: Your account's number.
keyobject: name and scope of the key this request was sent with.
balancesobject: One entry per coin, keyed by coin (firo, pivx, ...).
balances.*.balancestring: What the balance holds, in the coin.
balances.*.rate_usdstring | null: The coin's price in USD now; null when we have no fresh one.
balances.*.nodes_paidinteger: Masternodes of this coin with paid time left, or waiting for an address.
balances.*.nodes_auto_renewinteger: Of those, how many renew from the balance.
balances.*.cold_stakingboolean: PIVX cold staking is running and renews from the balance.
balances.*.cost_per_day_usdstring: What the renewals cost per day, in USD.
balances.*.cost_per_daystring | null: The same in the coin at this moment's rate; null without one.
balances.*.covered_untilinteger | null: When the balance stops covering the next renewal. At most ten years ahead; null when nothing renews from it, or without a rate.

Example

curl -H "Authorization: Bearer $MNS_KEY" https://masternode.space/api/v1.0/account

{
  "response": {
    "user_id": 42,
    "key": { "name": "monitoring", "scope": "read" },
    "balances": {
      "firo": {
        "coin": "firo",
        "ticker": "FIRO",
        "balance": "150.00000000",
        "rate_usd": "1.25000000",
        "nodes_paid": 40,
        "nodes_auto_renew": 40,
        "cold_staking": false,
        "cost_per_day_usd": "13.3333",
        "cost_per_day": "11.20000000",
        "covered_until": 1795000000
      }
    }
  }
}

GET /coins read key

Coins, prices and fields

What can be hosted, what a month costs, and the fields a new masternode of each coin is sent with - everything a script needs before its first POST to /nodes.

Answer

coinsobject: One entry per coin, keyed by coin.
coins.*.statusstring: live can be ordered; soon not yet.
coins.*.node_typestring: deterministic (Firo, Dash, Kerrigan: a ProTx hash and a BLS operator key) or legacy (PIVX: the collateral output and a masternode key).
coins.*.collateralinteger: The collateral of a masternode we host, in whole coins.
coins.*.price_month_usdstring: A month of hosting, in USD.
coins.*.rate_usdstring | null: The coin's price in USD now.
coins.*.price_monthstring | null: A month in the coin, as an order would be priced now; null when there is no fresh rate, and nothing can be ordered.
coins.*.addresses_freeinteger: Addresses free for new masternodes. One paid for while there are none waits for one, its time held.
coins.*.registration_updatesboolean: We point a registration at the address we give it (protx update_service), and can revive a banned masternode. Where false, you send that from your wallet.
coins.*.fieldslist: The fields a new masternode is sent with: name, format, label, hint.
coins.*.lookup_fieldslist | null: On a deterministic coin, what can be sent instead of collateral_ref: the collateral output, from which the ProTx hash is looked up.

Example

curl -H "Authorization: Bearer $MNS_KEY" https://masternode.space/api/v1.0/coins

GET /nodes read key

List masternodes

Every masternode on the account, newest first - up to 500. Each is a masternode object (below), with what the network said of it at the last check and the latest change of its registration.

The network is read every few minutes for every running masternode, so polling this more often than once a minute shows nothing new.

Answer

nodeslist: Masternode objects.
totalinteger: How many masternodes the account has.
truncatedboolean: There are more than the list holds; the oldest are left out.

Example

curl -H "Authorization: Bearer $MNS_KEY" https://masternode.space/api/v1.0/nodes

{
  "response": {
    "nodes": [
      {
        "id": 1207,
        "name": "MN_FIRO_1207",
        "coin": "firo",
        "type": "deterministic",
        "state": "running",
        "address": "203.0.113.24:8168",
        "ip": "203.0.113.24",
        "port": 8168,
        "configured": true,
        "collateral_ref": "6c1d...e93a",
        "collateral_index": null,
        "paid_until": 1796000000,
        "credit_seconds": 0,
        "auto_renew": true,
        "removable": false,
        "created_at": 1790000000,
        "chain": {
          "status": "ENABLED",
          "service": "203.0.113.24:8168",
          "pose_penalty": 0,
          "payee": "a8Uq...Wd1",
          "last_paid": 1793990000,
          "checked_at": 1794000000,
          "stale": false
        },
        "registration_update": null
      }
    ],
    "total": 1,
    "truncated": false
  }
}

GET /nodes/{id} read key

One masternode

One masternode object, by its id.

Answer

nodeobject: The masternode.

Refused with

404node_unknown

Example

curl -H "Authorization: Bearer $MNS_KEY" https://masternode.space/api/v1.0/nodes/1207

POST /nodes write key

Add a masternode

Hosts a masternode you hold the keys for, pays for it from the balance, and answers with its address. It has to be registered on the network already, and on a deterministic coin the operator key has to be the one its registration names.

Its registration still names its old address. Where registration_updates is true for the coin we point it at the new one ourselves within minutes - which also lifts a PoSe ban, so this is how a masternode banned somewhere else is brought back here. Elsewhere, send protx update_service with the new address from your wallet.

The price is quoted and charged in the same request; max_total refuses a price above yours. The network is asked about the masternode only once the balance covers the price.

Body

coinstringrequired: A coin from /coins whose status is live.
operator_keystringrequired: The BLS operator secret key (64 hex) on a deterministic coin; the masternode private key on PIVX.
collateral_refstringrequired: The ProTx hash on a deterministic coin; the collateral transaction id on PIVX.
collateral_indexintegerPIVX only: The collateral's output index.
collateral_txidstringoptional: Instead of collateral_ref on a deterministic coin: the collateral transaction, with collateral_output. The ProTx hash is looked up from it.
collateral_outputintegeroptional: The collateral's output index, with collateral_txid.
monthsintegerdefault: 1: How many months to pay for, 1 to 24.
auto_renewbooleandefault: true: Renew it from the balance before its time ends.
max_totalstringoptional: The most you will pay, in the coin. A higher price is refused with price_above_max and nothing is charged.

Answer

nodeobject: The new masternode. address is null and state is awaiting when no address was free: it gets the next one, and its time starts then.
chargedstring: What was taken from the balance, in the coin.
balancestring: The balance after it.

Example

curl -X POST -H "Authorization: Bearer $MNS_KEY" -H "Content-Type: application/json" \
  -d '{"coin": "firo", "collateral_ref": "6c1d...e93a", "operator_key": "4f0b...77c2", "months": 1, "max_total": "9.5"}' \
  https://masternode.space/api/v1.0/nodes

PATCH /nodes/{id} write key

Change a masternode

Turns auto-renewal on or off, or takes a new operator key - after protx update_registrar gave the registration one, say. A new key is checked against the registration first, as on the site. Send either, or both.

Body

auto_renewbooleanoptional: Renew it from the balance 3 days before its time ends, 1 month at a time.
operator_keystringoptional: Its operator key from now on. Only for a masternode that has been set up.

Answer

nodeobject: The masternode, changed.

Refused with

422nothing_to_change
422invalid_field
409node_not_configured
422collateral_operator
429too_many_lookups
503chain_unavailable
404node_unknown

Example

curl -X PATCH -H "Authorization: Bearer $MNS_KEY" -H "Content-Type: application/json" \
  -d '{"auto_renew": false}' https://masternode.space/api/v1.0/nodes/1207

POST /nodes/{id}/renew write key

Renew from the balance

Pays for more months now, from the balance - the same as Pay on the dashboard with "from the balance" chosen. A masternode whose time ran out is started again, on its old address when it is still free.

Body

monthsintegerdefault: 1: 1 to 24.
max_totalstringoptional: The most you will pay, in the coin.

Answer

nodeobject: The masternode, with its new paid_until.
order_idinteger: The order, as the dashboard lists it.
monthsinteger: Months paid for.
chargedstring: What was taken from the balance.
balancestring: The balance after it.

Refused with

409balance_short
409price_above_max
409node_in_flight
409order_in_flight
409node_awaiting_address
409node_unpaid
409coin_not_live
409node_no_capacity
503order_no_price
503order_no_address
404node_unknown

Example

curl -X POST -H "Authorization: Bearer $MNS_KEY" -H "Content-Type: application/json" -d '{"months": 3}' \
  https://masternode.space/api/v1.0/nodes/1207/renew

POST /nodes/{id}/revive write key

Revive a PoSe-banned masternode

For a masternode running here that the network has PoSe-banned. We ask the network first, and only a banned masternode is revived - calling this for one that is not costs nothing and changes nothing.

Within a minute we send protx update_service to the same address, signed with its operator key; the network takes it as the masternode saying it is back, and lifts the ban once it is mined. Follow it in registration_update and chain.status.

At most 3 updates of one masternode a week: a masternode that keeps being banned needs a person, and we are told of every revival.

Answer

outcomestring: queued, or open when an update of it is on its way already.
ban_heightinteger: The block it was banned at.
nodeobject: The masternode, with the update in registration_update.

Refused with

409not_banned
409not_running
409unregistered
409not_supported
409update_stopped
429update_limit
429too_many_lookups
503chain_unavailable
404node_unknown

Example

curl -X POST -H "Authorization: Bearer $MNS_KEY" https://masternode.space/api/v1.0/nodes/1207/revive

DELETE /nodes/{id} write key

Delete a masternode

Only one that is not running and has no paid time left - removable says which. One with time left is not deleted: turn auto_renew off, and it stops when its time ends.

Answer

deletedboolean: Always true.
idinteger: The masternode deleted.

Refused with

409node_paid
409node_in_flight
409node_sign_sent
404node_unknown

Example

curl -X DELETE -H "Authorization: Bearer $MNS_KEY" https://masternode.space/api/v1.0/nodes/1207

The masternode object

What every /nodes answer describes a masternode with. Its operator key is never in it.

idinteger: Its number - the one in the path.
namestring: Its name in masternode.conf, such as MN_FIRO_1207. Quote it when you ask us about it.
coinstring: Its coin.
typestring: deterministic or legacy.
statestring: unpaid - never paid for; awaiting - paid, waiting for a free address, its time held; setup - has an address, waiting for its credentials (on the site); starting - set up, goes live within a minute; running - live on the network; expired - its paid time ran out and its address was given back.
addressstring | null: ip:port, as masternode.conf has it - IPv6 in brackets. What its registration has to name.
ipstring | null: The address alone.
portinteger | null: The port alone.
configuredboolean: Its credentials are in.
collateral_refstring | null: The ProTx hash on a deterministic coin; the collateral transaction on PIVX.
collateral_indexinteger | null: The collateral's output, on PIVX.
paid_untilinteger | null: When its paid time ends.
credit_secondsinteger: Paid time not started yet, while it waits for an address.
auto_renewboolean: It renews from the balance.
removableboolean: It can be deleted now.
created_atinteger: When it was added.
chainobject | null: What the network said of it at the last check; null before the first.
chain.statusstring: The network's own word: ENABLED or POSE_BANNED on a deterministic coin; ENABLED, PRE_ENABLED, EXPIRED, VIN_SPENT or REMOVE on PIVX; MISSING when the network does not list it.
chain.servicestring | null: The ip:port its registration names. Not its address: the registration points somewhere else.
chain.pose_penaltyinteger | null: Its PoSe penalty, where the coin reports one. It climbs before a ban.
chain.payeestring | null: Where its rewards are paid.
chain.last_paidinteger | null: When a block last paid it.
chain.checked_atinteger: When this was read.
chain.staleboolean: Not read for 20 minutes - it is not running, or the coin's node is down.
registration_updateobject | null: The latest protx update_service we sent or are sending for it.
registration_update.kindstring: move - pointing the registration at its address; revive - the same transaction, to lift a PoSe ban.
registration_update.statusstring: queued; sending - sent, waiting to be mined; done; failed or cancelled - stopped, and we have been told; superseded - a newer one replaced it.
registration_update.servicestring: The address it points the registration at.
registration_update.tx_idstring | null: The transaction, once sent.
registration_update.id, created_at, updated_atinteger: Its number, and when it was made and last changed.

Error codes

400invalid_json: The body is not a JSON object.
400query_string: The URL has a query string. Parameters go in the path or the body.
401unauthorized: No key, or a key that is not valid any more.
403read_only_key: A read key sent a request that changes something.
403account_blocked: The key's account is blocked.
404not_found: No such path.
404node_unknown: No masternode with this id on your account.
405method_not_allowed: The path does not take this method; allowed lists the ones it does.
413body_too_large: The body is larger than 16 KB.
422missing_field: A required field was not sent; field names it.
422invalid_field: A credential is not in its format; field names it.
422invalid_parameter: A parameter is of the wrong type or out of range; field names it.
422nothing_to_change: A PATCH with nothing in it.
422coin_unknown: No such coin.
422collateral_*: The network does not agree with the credentials - collateral_protx: no such registration; collateral_operator: not its operator key; collateral_unregistered: no registration uses that collateral; and others, each with its reason in message.
409balance_short: The balance does not cover it: price is what it costs, balance what the balance holds, short the difference.
409price_above_max: It costs more than max_total; price says what it costs.
409coin_not_live: The coin is not open for hosting now.
409node_collateral_taken: That masternode is hosted here already.
409node_no_capacity: No address is free for the coin.
409node_not_configured: The masternode has not been set up yet.
409node_paid: It is running or has paid time left, so it cannot be deleted.
409node_in_flight: A payment for it is being confirmed.
409node_sign_sent: A registration naming its new operator key has just been sent; it can be deleted once that is in a block, or in an hour at most.
409order_in_flight: An order for it is being paid already; wait for that one.
409node_awaiting_address: It is paid for and waiting for an address.
409node_unpaid: It was never paid for.
409not_banned: The network has not banned it.
409not_running: It is not running.
409unregistered: The network has no registration with its ProTx hash.
409not_supported: Its coin has no revivals here.
409update_stopped: An update of its registration stopped and waits for us.
429too_many_requests: More than 60 requests a minute from your address.
429too_many_lookups: The account's lookups on the network for the hour are used up; retry_after says for how long, in seconds.
429update_limit: Its registration was updated 3 times this week.
500internal_error: Our fault. It is logged; try again later.
503chain_unavailable: The coin's network could not be asked. Try again in a minute.
503order_no_price: No fresh exchange rate to price it at. Try again in a minute.
503order_no_address: The coin cannot be paid for here at the moment. Tell us.
503maintenance: We are down for maintenance; retry_after says when to try again.

Bringing back a banned masternode

There is no restart: the way our hosting is built does not need one, and a masternode stays up for as long as it is paid for. What a restart is for elsewhere - a PoSe ban - is what a revival is for here.

Every few minutes, GET /nodes and look at each chain.status.
One hosted here is POSE_BANNED: POST /nodes/{id}/revive. The ban is lifted once our transaction is mined - follow it in registration_update.
One hosted somewhere else is banned: POST /nodes with its ProTx hash and operator key. The answer has its new address; where the coin's registration_updates is true we point its registration there ourselves, and that lifts the ban as well. Elsewhere, send protx update_service with the new address from your wallet.

Keep auto_renew on and the balance above a few days of cost_per_day (GET /account), and none of them stops for want of payment.