Nodes API

Interact with the nodes API to get information about your nodes or create new ones.

The node model

The node list, details or create endpoints all return one or multiple node models. Here is the node properties reference:

Property

Type

Description

id

UUID

Unique ID of the node across the GIN Platform

name

string

Custom name of the node (default null)

blockchain

string

ID of the blockchain model

collateral

integer

Numeric amount of node collateral

dedicated

boolean

true for Dedicated nodes, false for Cloud nodes

ip

object

  • v4: the IPv4 of the node

  • v6: the IPv6 of the node

  • default: the default IP address to be used (usually IPv4)

pk

string

Private key used to start the node. Usually output of the masternode genkey command for DASH/PIVX enabled nodes.

tx

object

Details of the collateral transaction

  • id: the transaction ID

  • index: the transaction output index

  • confirmations: only number of current confirmations; only appears before the node becomes STARTED.

status

string

The GIN Platform status of the node:

  • installing: the node installation started

  • syncing: the node is syncing its blockchain data

  • waitingtransconfirm: waiting for the collateral transaction to reach the required number of confirmations (blockchain model -> mn_confirmations)

  • waitingstart: the node runs but awaits wallet activation (user action required)

  • started: the node runs and was correctly started from the wallet

  • cleaningup: the node started uninstalling from its host

  • cleanedup: the node was successfully uninstalled

masternode_status

string

The blockchain status of the node:

  • PRE_ENABLED: the node was just started and awaits the other nodes to validate its registration

  • ENABLED: the node is active and receiving rewards

  • ACTIVE: similar to ENABLED

  • EXPIRED: the node is not found in the masternodes list anymore or is de-synced with the network

  • NEW_START_REQUIRED: the node was inactive for a while, it probably needs a re-sync and restart

  • OUTPOINT_SPENT: the collateral transaction outputs were spent in another transaction

  • UPDATE_REQUIRED: the node runs an outdated version of the blockchain daemon

  • WATCHDOG_EXPIRED: sentinel is not configured properly; only on sentinel enabled blockchains

  • POSE_BAN: the node was banned by the other network participants

address

string

Blockchain address where the collateral amount is and rewards are received

port_status

boolean

true if the p2p port of the node is reachable from the outside; false if the p2p port of the node is closed

created_at

datetime

The date and time of the node creation

expires_at

datetime

The date and time of the expiry of the hosting service. Renewal happens automatically before that date and the expiry is extended if there is enough balance

updated_at

datetime

The date and time of the last change of data on the model

updated_mnstatus_at

datetime

The date and time of the last update of the masternode_status property

updated_portstatus_at

datetime

The date and time of the last update of the port_status property

updated_financials_at

datetime

The date and time of the last update of financial data like the received rewards

last_started_at

datetime

The date and time of the last node start (wallet start)

financials

object

Object containing computed financial data:

  • last_reward_at: datetime

  • rewards: sum of all time rewards

  • rewards_today: sum of rewards in the last 24h

  • rewards_month: sum of rewards in the last 30 days

  • exits: sum of rewards that left the node address

  • exits_btc_val: sum of BTC value of exists at the time of the exit event

meta

object

Object holding arbitrary data in a key/value pair store. The limits are:

  • max 10 keys

  • max key length: 50 characters

  • max value length: 255 characters

The meta object can be used to store information from an external system.

get
Get nodes list

https://api.ginplatform.io/nodes
Get a list of all your nodes.
Request
Response
Request
Headers
Authorization
required
string
Bearer API_KEY
Query Parameters
active
optional
string
If the parameter is present (/nodes?active) only the non-expired nodes will be returned
Response
200: OK
A list of node models.
[
{
"id": "1d9f1930-de86-11e8-93ee-31e36a5e0000",
"name": null,
"blockchain": "gincoin",
"collateral": 1000,
"dedicated": true,
"ip": {
"v4": "104.238.145.000",
"v6": null,
"default": "104.238.145.000"
},
"pk": "7ehJPyNZKG2RfEKRm9KXrrhJDDJgvi2zxZCbS4FXSER2q9g0000",
"tx": {
"id": "f0725c318214047d413ca136d27419813803da44a66513e0d1d282367a990000",
"index": 1
},
"status": "started",
"masternode_status": "ENABLED",
"address": "GgbFhCY39zgp4ixxzetL5gySrBJRSS0000",
"port_status": true,
"created_at": "2018-11-02T16:34:52.843Z",
"expires_at": "2018-11-14T16:34:52.842Z",
"updated_at": "2018-11-14T11:06:04.759Z",
"updated_mnstatus_at": "2018-11-14T11:06:04.759Z",
"updated_portstatus_at": "2018-11-14T11:06:24.676Z",
"updated_financials_at": "2018-11-14T10:56:21.711Z",
"financials": {
"last_reward_at": "2018-11-14T20:48:24.000Z",
"rewards": 20,
"rewards_today": 10,
"rewards_month": 20,
"exits": 5.243,
"exits_btc_val": 0.0002
},
"meta": {}
},
{
"id": "b7b9fd70-d92f-11e8-9396-197030d50000",
"name": null,
"blockchain": "zen",
"collateral": 42,
"dedicated": true,
"ip": {
"v4": "95.216.194.000",
"v6": null,
"default": "95.216.194.000"
},
"pk": null,
"tx": {},
"status": "started",
"masternode_status": "ACTIVE",
"address": "znayAsUJe3Gzi5pJ1RZr16VbMpheod40000",
"port_status": true,
"created_at": "2018-10-28T11:27:25.861Z",
"expires_at": "2018-11-15T11:27:25.861Z",
"updated_at": "2018-11-14T11:09:39.401Z",
"updated_mnstatus_at": "2018-11-14T11:09:39.401Z",
"updated_portstatus_at": "2018-11-14T11:05:40.243Z",
"updated_financials_at": "2018-11-14T11:02:39.235Z",
"financials": {
"last_reward_at": "2018-11-14T20:48:24.000Z",
"rewards": 20,
"rewards_today": 10,
"rewards_month": 20,
"exits": 5.243,
"exits_btc_val": 0.0002
},
"meta": {}
}
]

get
Get node details

https://api.ginplatform.io/nodes/:id
Get details of a particular node
Request
Response
Request
Path Parameters
id
optional
string
The id property of the node
Headers
Authorization
required
string
Bearer API_KEY
Response
200: OK
{
"id": "1d9f1930-de86-11e8-93ee-31e36a5e0000",
"name": null,
"blockchain": "gincoin",
"collateral": 1000,
"dedicated": true,
"ip": {
"v4": "104.238.145.000",
"v6": null,
"default": "104.238.145.000"
},
"pk": "7ehJPyNZKG2RfEKRm9KXrrhJDDJgvi2zxZCbS4FXSER2q9g0000",
"tx": {
"id": "f0725c318214047d413ca136d27419813803da44a66513e0d1d282367a990000",
"index": 1
},
"status": "started",
"masternode_status": "ENABLED",
"address": "GgbFhCY39zgp4ixxzetL5gySrBJRSS0000",
"port_status": true,
"created_at": "2018-11-02T16:34:52.843Z",
"expires_at": "2018-11-14T16:34:52.842Z",
"updated_at": "2018-11-14T11:06:04.759Z",
"updated_mnstatus_at": "2018-11-14T11:06:04.759Z",
"updated_portstatus_at": "2018-11-14T11:06:24.676Z",
"updated_financials_at": "2018-11-14T10:56:21.711Z",
"financials": {
"last_reward_at": "2018-11-14T20:48:24.000Z",
"rewards": 20,
"rewards_today": 10,
"rewards_month": 20,
"exits": 5.243,
"exits_btc_val": 0.0002
},
"meta": {
"test-key": "test-value"
}
}
404: Not Found
no content

post
Create node

https://api.ginplatform.io/nodes
The body of the request needs to be a raw JSON containing the keys listed under Body Parameters
Request
Response
Request
Headers
Authorization
required
string
Bearer API_KEY
Content-Type
required
string
application/json
Body Parameters
dedicated
optional
boolean
Whether the node is a Dedicated node or Cloud node
blockchain
required
string
ID of the blockchain for the new node
collateral
optional
integer
The amount of the collateral transaction. Multi-collateral support is enabled by this parameter for tiered nodes.
txid
required
string
Collateral transaction ID
meta
optional
object
Object to store in the meta field
Response
200: OK
{
"id": "1d9f1930-de86-11e8-93ee-31e36a5e0000",
"name": null,
"blockchain": "gincoin",
"collateral": 1000,
"dedicated": true,
"ip": {
"v4": "104.238.145.000",
"v6": null,
"default": "104.238.145.000"
},
"pk": "7ehJPyNZKG2RfEKRm9KXrrhJDDJgvi2zxZCbS4FXSER2q9g0000",
"tx": {
"id": "f0725c318214047d413ca136d27419813803da44a66513e0d1d282367a990000",
"index": 1
},
"status": "installing",
"masternode_status": null,
"address": "GgbFhCY39zgp4ixxzetL5gySrBJRSS0000",
"port_status": false,
"created_at": "2018-11-02T16:34:52.843Z",
"expires_at": "2018-11-03T16:34:52.842Z",
"updated_at": "2018-11-02T16:34:52.843Z",
"updated_mnstatus_at": null,
"updated_portstatus_at": null,
"updated_financials_at": null,
"financials": {
"last_reward_at": null,
"rewards": 0,
"rewards_today": 0,
"rewards_month": 0,
"exits": 0,
"exits_btc_val": 0
},
"meta": {
"test-key": "test-value"
}
}

post
Update node

https://api.ginplatform.io/nodes/:id
Update node data, currently only the meta property change is supported.
Request
Response
Request
Path Parameters
id
required
string
ID of the node to be updated
Headers
Content-Type
optional
string
application/json
Authorization
required
string
Bearer API_KEY
Body Parameters
name
optional
string
Custom name of the node
meta
optional
object
New value of the meta to store with the node
Response
200: OK
{
"id": "1d9f1930-de86-11e8-93ee-31e36a5e0000",
"name": null,
"blockchain": "gincoin",
"collateral": 1000,
"dedicated": true,
"ip": {
"v4": "104.238.145.000",
"v6": null,
"default": "104.238.145.000"
},
"pk": "7ehJPyNZKG2RfEKRm9KXrrhJDDJgvi2zxZCbS4FXSER2q9g0000",
"tx": {
"id": "f0725c318214047d413ca136d27419813803da44a66513e0d1d282367a990000",
"index": 1
},
"status": "installing",
"masternode_status": null,
"address": "GgbFhCY39zgp4ixxzetL5gySrBJRSS0000",
"port_status": false,
"created_at": "2018-11-02T16:34:52.843Z",
"expires_at": "2018-11-03T16:34:52.842Z",
"updated_at": "2018-11-02T16:34:52.843Z",
"updated_mnstatus_at": null,
"updated_internal_status_at": null,
"updated_portstatus_at": null,
"updated_financials_at": null,
"financials": {
"last_reward_at": "2018-11-14T20:48:24.000Z",
"rewards": 20,
"rewards_today": 10,
"rewards_month": 20,
"exits": 5.243,
"exits_btc_val": 0.0002
},
"meta": {
"test-key": "test-value"
}
}

delete
Delete node

https://api.ginplatform.io/nodes/:id
ATTENTION! this action is destructive and can not be undone.
Request
Response
Request
Path Parameters
id
required
string
ID of the node to be deleted
Headers
Authorization
required
string
Bearer API_KEY
Response
204: No Content
The node was deleted.
404: Not Found
If the node ID is incorrect or it was already deleted.
no content

post
Upgrade node

https://api.ginplatform.io/nodes/:id/upgrade
Convert an existing node from a Cloud node to Dedicated node. A new node will be created with the same collateral transaction and private key. The new node will go through all the steps of a standard installation and at the end will need starting from the wallet.
Request
Response
Request
Path Parameters
id
required
string
ID of the node to be upgraded
Headers
Authorization
required
string
Bearer API_KEY
Response
200: OK

post
Downgrade node

https://api.ginplatform.io/nodes/:id/downgrade
Convert an existing node from Dedicated node to Cloud node. A new node will be created with the same collateral transaction and private key. The new node will go through all the steps of a standard installation and at the end will need starting from the wallet.
Request
Response
Request
Path Parameters
id
required
string
ID of the node to be downgraded
Headers
Authorization
required
string
Bearer API_KEY
Response
200: OK

post
Rebuild node

https://api.ginplatform.io/nodes/:id/rebuild
Rebuild a node after it expired because of no funding available for renewal. The node will be provisioned on a new server and get a new IP, but the same TX ID and private key (where applicable) will be used.
Request
Response
Request
Path Parameters
id
required
string
ID of the node to be rebuilt
Headers
Authorization
required
string
Bearer API_KEY
Response
200: OK

get
Get node rewards

https://api.ginplatform.io/nodes/:id/rewards
Request
Response
Request
Path Parameters
id
required
string
ID of the node
Headers
Authorization
required
string
Bearer API_KEY
Query Parameters
page
optional
integer
Page to display. Defaults to 1.
Response
200: OK
{
"total": 2,
"list": [
{
"date": "2018-11-28T07:09:42.000Z",
"amount": 10,
"amount_btc": 0.00398,
"txid": "d9837160541ac36848ea7952972d747b29c19f3367279b796b472e0000000000",
"block_hash": "000000000000b080e009501f9a153d3d057d8878f1ba8474039fc00000000000"
},
{
"date": "2018-11-24T00:29:47.000Z",
"amount": 10,
"amount_btc": 0.0036229,
"txid": "fc8b920a41a4b9a49801018cd674b653e9fdabbe7d42fe99d7cf160000000000",
"block_hash": "000000000006bedc7d00df21b478f59b04620dde0116fe1b8fff510000000000"
}
]
}