api-reference.md

title: GoShimmer API
language_tabs:
  - go: Go
  - shell: Shell
  - javascript--nodejs: Node.JS
  - python: Python
toc_footers: []
includes: []
search: true
highlight_theme: darkula
headingLevel: 2

GoShimmer API v0.1.0

The GoShimmer API provides a simple and consistent way to get transactions from the Tangle, get a node's neighbors, or send new transactions.
This API accepts HTTP requests and responds with JSON data.

Base URLs

All requests to this API should be prefixed with the following URL:

<a href="http://localhost:8080">http://localhost:8080</a>

POST /broadcastData

Creates a zero-value transaction and attaches it to the Tangle.

Creates a zero-value transaction that includes the given data in the signatureMessageFragment field and the given address in the address field.
This endpoint also does tip selection and proof of work before attaching the transaction to the Tangle.

Body parameters

{
  "address": "string",
  "data": "string"
}

Body parameters

Name	Type	Required	Description
body	object	true	Request object
» address	string	true	Address to add to the transaction's address field.
» data	string	false	Data to add to the transaction's signatureMessageFragment field. The data must be no larger than 2187 bytes, and the address must contain only trytes and be either 81 trytes long or 90 trytes long, including a checksum.

Examples

---

Go

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "http://localhost:8080/broadcastData", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

---

cURL

# You can also use wget
curl -X POST http://localhost:8080/broadcastData \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

---

Node.js

const fetch = require('node-fetch');
const inputBody = '{
  "address": "string",
  "data": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('http://localhost:8080/broadcastData',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

---

Python

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('http://localhost:8080/broadcastData', params={

}, headers = headers)

print r.json()

---

Response examples

200 Response

{
  "hash": "99IJMBGYVUAYAFAZFGAIVCFWMXP9WTDPX9JDFJLFKNUBLGRRHBERVTTJUZPRRTKKKNMMVX9PYGBKA9999"
}

Response examples

Status	Meaning	Description	Schema
200	OK	Successful response	Inline
400	Bad Request	Error response	Inline

Response examples

Status Code 200

Field	Type	Description
» hash	string	The transaction's hash on the Tangle.

Status Code 400

Field	Type	Description
» message	string	The error message.

POST /findTransactionHashes

Gets any transaction hashes that were sent to the given addresses.

Searches the Tangle for transactions that contain the given addresses and returns an array of the transactions hashes that were found. The transaction hashes are returned in the same order as the given addresses. For example, if the node doesn't have any transaction hashes for a given address, the value at that index in the returned array is empty.

Body parameters

{
  "addresses": [
    "string"
  ]
}

Body parameters

Name	Type	Required	Description
body	object	true	Request object
» addresses	[string]	true	Addresses to search for in transactions. Addresses must contain only trytes and be either 81 trytes long or 90 trytes long, including a checksum.

Examples

---

Go

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "http://localhost:8080/findTransactionHashes", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

---

cURL

# You can also use wget
curl -X POST http://localhost:8080/findTransactionHashes \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

---

Node.js

const fetch = require('node-fetch');
const inputBody = '{
  "addresses": [
    "string"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('http://localhost:8080/findTransactionHashes',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

---

Python

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('http://localhost:8080/findTransactionHashes', params={

}, headers = headers)

print r.json()

---

Response examples

200 Response

{
  "transactions": [
    [
      "string"
    ]
  ]
}

Response examples

Status	Meaning	Description	Schema
200	OK	Successful response	Inline

Response examples

Status Code 200

Field	Type	Description
» transactions	[array]

POST /getTransactionObjectsByHash

Gets transactions objects for the given transaction hashes

Searches the Tangle for transactions with the given hashes and returns their contents as objects. The transaction objects are returned in the same order as the given hashes. If any of the given hashes is not found, an error is returned.

Body parameters

{
  "hashes": [
    "string"
  ]
}

Body parameters

Name	Type	Required	Description
body	object	true	Request object
» hashes	[string]	true	Transaction hashes to search for in the Tangle. Transaction hashes must contain only 81 trytes.

Examples

---

Go

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "http://localhost:8080/getTransactionObjectsByHash", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

---

cURL

# You can also use wget
curl -X POST http://localhost:8080/getTransactionObjectsByHash \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

---

Node.js

const fetch = require('node-fetch');
const inputBody = '{
  "hashes": [
    "string"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('http://localhost:8080/getTransactionObjectsByHash',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

---

Python

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('http://localhost:8080/getTransactionObjectsByHash', params={

}, headers = headers)

print r.json()

---

Response examples

200 Response

{
  "transaction": [
    {
      "hash": "string",
      "weightMagnitude": 0,
      "trunkTransactionHash": "string",
      "branchTransactionHash": "string",
      "head": true,
      "tail": true,
      "nonce": "string",
      "address": "string",
      "timestamp": 0,
      "signatureMessageFragment": "string"
    }
  ]
}

Response examples

Status	Meaning	Description	Schema
200	OK	Successful response	Inline
404	Not Found	Transaction(s) not found	None

Response examples

Status Code 200

Field	Type	Description
» transaction	[Transaction]
»» hash	string
»» weightMagnitude	integer
»» trunkTransactionHash	string
»» branchTransactionHash	string
»» head	boolean
»» tail	boolean
»» nonce	string
»» address	string
»» timestamp	integer
»» signatureMessageFragment	string

POST /getTransactionTrytesByHash

Gets the transaction trytes of given transaction hashes.

Searches the Tangle for transactions with the given hashes and returns their contents in trytes. The transaction trytes are returned in the same order as the given hashes. If any of the given hashes is not found, an error is returned.

Body parameters

{
  "hashes": [
    "string"
  ]
}

Body parameters

Name	Type	Required	Description
body	object	true	Request object
» hashes	[string]	true	Transaction hashes to search for in the Tangle. Transaction hashes must contain only 81 trytes.

Examples

---

Go

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "http://localhost:8080/getTransactionTrytesByHash", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

---

cURL

# You can also use wget
curl -X POST http://localhost:8080/getTransactionTrytesByHash \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

---

Node.js

const fetch = require('node-fetch');
const inputBody = '{
  "hashes": [
    "string"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('http://localhost:8080/getTransactionTrytesByHash',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

---

Python

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('http://localhost:8080/getTransactionTrytesByHash', params={

}, headers = headers)

print r.json()

---

Response examples

200 Response

{
  "trytes": [
    "string"
  ]
}

Response examples

Status	Meaning	Description	Schema
200	OK	Successful response	Inline
404	Not Found	Transactions not found	None

Response examples

Status Code 200

Field	Type	Description
» trytes	[string]

GET /getTransactionsToApprove

Gets two tip transactions from the Tangle.

Runs the tip selection algorithm and returns two tip transactions hashes.
You can use these hashes in the branch and trunk transaction fields of a new transaction.

Examples

---

Go

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "http://localhost:8080/getTransactionsToApprove", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

---

cURL

# You can also use wget
curl -X GET http://localhost:8080/getTransactionsToApprove \
  -H 'Accept: application/json'

---

Node.js

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('http://localhost:8080/getTransactionsToApprove',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

---

Python

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('http://localhost:8080/getTransactionsToApprove', params={

}, headers = headers)

print r.json()

---

Response examples

200 Response

{
  "branchTransaction": "string",
  "trunkTransaction": "string"
}

Response examples

Status	Meaning	Description	Schema
200	OK	Successful response	Inline

Response examples

Status Code 200

Field	Type	Description
» branchTransaction	string
» trunkTransaction	string

GET /spammer

Sends spam transactions.

Sends zero-value transactions at the given rate per second.
You can start the spammer, using the cmd=start command and stop it, using the cmd=stop command. Optionally, a parameter tps can be provided (i.e., tps=10) to change the default rate (tps=1).

Body parameters

Name	Type	Required	Description
cmd	string	true	Command to either start or stop spamming.
tps	integer	false	Change the sending rate.

Enumerated Values

Parameter	Value
cmd	start
cmd	stop

Examples

---

Go

package main

import (
       "bytes"
       "net/http"
)

func main() {

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "http://localhost:8080/spammer", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

---

cURL

# You can also use wget
curl -X GET http://localhost:8080/spammer?cmd=start

---

Node.js

const fetch = require('node-fetch');

fetch('http://localhost:8080/spammer?cmd=start',
{
  method: 'GET'

})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

---

Python

import requests

r = requests.get('http://localhost:8080/spammer', params={
  'cmd': 'start'
)

print r.json()

---

Response examples

Status	Meaning	Description	Schema
200	OK	Successful Response	None
404	Not Found	invalid command in request	None

GET /getNeighbors

Gets the node's chosen and accepted neighbors.

Returns the node's chosen and accepted neighbors. Optionally, you can pass the known=1 query parameter to return all known peers.

Body parameters

Name	Type	Required	Description
known	integer	false	Returns all known peers when set to 1.

Examples

---

Go

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "http://localhost:8080/getNeighbors", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

---

cURL

# You can also use wget
curl -X GET http://localhost:8080/getNeighbors \
  -H 'Accept: application/json'

---

Node.js

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('http://localhost:8080/getNeighbors',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

---

Python

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('http://localhost:8080/getNeighbors', params={

}, headers = headers)

print r.json()

---

Response examples

200 Response

{
  "chosen": [
    {
      "id": "V8LYtWWcPYYDTTXLeIEFjJEuWlsjDiI0+Pq",
      "publicKey": "V8LYtWWcPYYDTTXLeIEFjJEuWlsjDiI0+Pq",
      "services": [
        {
          "id": "peering",
          "address": "198.51.100.1:80"
        }
      ]
    }
  ],
  "accepted": [
    {
      "id": "V8LYtWWcPYYDTTXLeIEFjJEuWlsjDiI0+Pq",
      "publicKey": "V8LYtWWcPYYDTTXLeIEFjJEuWlsjDiI0+Pq",
      "services": [
        {
          "id": "peering",
          "address": "198.51.100.1:80"
        }
      ]
    }
  ],
  "known": [
    {
      "id": "V8LYtWWcPYYDTTXLeIEFjJEuWlsjDiI0+Pq",
      "publicKey": "V8LYtWWcPYYDTTXLeIEFjJEuWlsjDiI0+Pq",
      "services": [
        {
          "id": "peering",
          "address": "198.51.100.1:80"
        }
      ]
    }
  ]
}

Response examples

Status	Meaning	Description	Schema
200	OK	Successful response	Inline
501	Not Implemented	Neighbor Selection/Discovery is not enabled	None

Response examples

Status Code 200

Field	Type	Description
» chosen	[Peer]
»» id	string
»» publicKey	string
»» services	[PeerService]
»»» id	string
»»» address	string
»» accepted	[Peer]
»» known	[Peer]

Schemas

Peer

{
  "id": "V8LYtWWcPYYDTTXLeIEFjJEuWlsjDiI0+Pq",
  "publicKey": "V8LYtWWcPYYDTTXLeIEFjJEuWlsjDiI0+Pq",
  "services": [
    {
      "id": "peering",
      "address": "198.51.100.1:80"
    }
  ]
}

Properties

Name	Type	Required	Description
id	string	false	ID of the peer node.
publicKey	string	false	Public key of the peer node.
services	[PeerService]	false	Services that the peer node is running.

PeerService

{
  "id": "peering",
  "address": "198.51.100.1:80"
}

Properties

Name	Type	Required	Description
id	string	false	ID of the service. Can be "peering", "gossip", or "fpc".
address	string	false	The IP address and port that the service is using.

Transaction

{
  "hash": "string",
  "weightMagnitude": 0,
  "trunkTransactionHash": "string",
  "branchTransactionHash": "string",
  "head": true,
  "tail": true,
  "nonce": "string",
  "address": "string",
  "timestamp": 0,
  "signatureMessageFragment": "string"
}

Properties

Name	Type	Required	Description
hash	string	false	Transaction hash.
weightMagnitude	integer	false	The weight magnitude of the transaction hash.
trunkTransactionHash	string	false	The transaction's trunk transaction hash.
branchTransactionHash	string	false	The transaction's branch transaction hash.
head	boolean	false	Whether this transaction is the head transaction in its bundle.
tail	boolean	false	Whether this transaction is the tail transaction in its bundle.
nonce	string	false	The transaction's nonce, which is used to validate the proof of work.
address	string	false	The address of the transaction.
timestamp	integer	false	The Unix epoch at which the transaction was created.
signatureMessageFragment	string	false	The transaction's signature or message.