NAV
Ruby Python JavaScript GO HTTP

Introduction

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

UTStamp is a simple API that allows you to stamp your data, providing an immutable and verifiable proof of existence and ownership. This document provides an overview of the API endpoints and operations.

Base URLs

The base URL for UTStamp's API is:

Authentication

The UTStamp API uses API keys to authenticate requests. You can obtain your API key by creating an account on our website.

To authenticate a request, include your API key in the license_key header of your HTTP requests:

license_key: {your-api-key}

Submission API

Submit

Code samples

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'license_key' => 'API_KEY'
}

result = RestClient.post 'https://api.utstamp.com/submissions',
  params: {
  }, headers: headers

p JSON.parse(result)


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

r = requests.post('https://api.utstamp.com/submissions', headers = headers)

print(r.json())


const inputBody = '{
  "entries": [
    {
      "hash": "a1b2c3...",
      "notes": "Example note 1"
    },
    {
      "hash": "d4e5f6...",
      "notes": "Example note 2"
    },
    {
      "hash": "g7h8i9...",
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'license_key':'API_KEY'
};

fetch('https://api.utstamp.com/submissions',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});


package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.utstamp.com/submissions", data)
    req.Header = headers

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


POST https://api.utstamp.com/submissions HTTP/1.1
Host: api.utstamp.com
license_key: 'API_KEY'
Content-Type: application/json

POST /submissions

The /submissions endpoint is used to submit hash + notes in bulk along with their corresponding notes, with a limit of 1000 entries per submission.

Please note that the hash value must be a SHA256 hash, in hexadecimal encoding. Duplicate hashes will not be processed again.

Body parameter

{
  "entries": [
    {
      "hash": "a1b2c3...",
      "notes": "Example note 1",
      "assets": "165c4038...",
      "priority": 1
    },
    {
      "hash": "d4e5f6...",
      "notes": "Example note 2",
      "priority": 5
    },
    {
      "hash": "g7h8i9...",
    }
  ]
}

Submissions Entry

Name Type Description
hash string Submission SHA256 hash
notes(optional) string Submission notes, optional
assets(optional) string Submission assets, optional
priority(optional) integer Submission priority, optional, value should be 0~5, 0->will be submitted in 20 mins, 1->1 hour, 2->2 hours, 3->4 hours, 4->8 hours, 5->24 hours

Response

Name Type Description
code integer 200
message string success

Query

Code samples

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json'
}

result = RestClient.get 'https://api.utstamp.com/submission/query?hash={hash}',
  params: {
  }, headers: headers

p JSON.parse(result)


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

r = requests.get('https://api.utstamp.com/submission/query?hash={hash}', headers = headers)

print(r.json())


const hash = "6241ded5917ee6a22a5e30f20a1866d151a076bafc64b14d5c28dc8cb146d2d9";
const headers = {
  'Content-Type':'application/json'
};

fetch('https://api.utstamp.com/submission/query?hash={hash}',
{
  method: 'GET',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});


package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.utstamp.com/submission/query?hash={hash}", data)
    req.Header = headers

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


GET https://api.utstamp.com/submission/query?hash={hash} HTTP/1.1
Host: api.utstamp.com
Content-Type: application/json

GET /submission/query

The /submission/query endpoint is used to query existing submission using hash.

Parameters

Name In Type Description
hash query string Submission SHA256 hash

If the submission exists, the response will be a UTStamp chain, If the chain is not built completly, a 408 response will be returned. Otherwise, a 404 response will be returned.

Response Body

Name Type Description
merkle_root string UTStamp block merkle tree root hash
submission_hash string submission SHA256 hash
bitcoin_stamp tx Bitcoin Null Data transaction info
timestamp integer submission created timestamp in mills
notes string submission notes if exists
content string submission content if exits
complement_path array of node submission validation complement path

Bitcoin Transaction Info

Name Type Description
txid string Bitcoin transaction id
data string Null Data transaction data
url string Bitcoin transaction url
accepted string transaction accepted time
confirmed string transaction confirmed time

UTStamp Validation Node

Name Type Description
hash string SHA256 hash in hexadecimal encoding
position string LEFT, RIGHT

Get UTStamp Block By Height

Code samples

require 'rest-client'
require 'json'

result = RestClient.get 'https://api.utstamp.com/block/height/{height}',
  params: {
  }

p JSON.parse(result)


import requests

r = requests.get('https://api.utstamp.com/block/height/{height}')

print(r.json())


const height = 20;
fetch('https://api.utstamp.com/block/height/{height}',
{
  method: 'GET'

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


package main

import (
       "bytes"
       "net/http"
)

func main() {

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.utstamp.com/block/height/{height}", data)
    req.Header = headers

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


GET https://api.utstamp.com/block/height/{height} HTTP/1.1
Host: api.utstamp.com

GET /block/height/{height}

Query the UTStamp block by height. Returns a 404 error if it does not exist.

Parameters

Name In Type Description
height path integer Stamp height

Get UTStamp Block By Root Hash

Code samples

require 'rest-client'
require 'json'

result = RestClient.get 'https://api.utstamp.com/block/root/{hash}',
  params: {
  }

p JSON.parse(result)


import requests

r = requests.get('https://api.utstamp.com/block/root/{hash}')

print(r.json())


const hash = "5527054d5e555d76de99cc68912a82b494bc9b7589910d2bf9f4a7ec79141085";
fetch('https://api.utstamp.com/block/root/{hash}',
{
  method: 'GET'

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


package main

import (
       "bytes"
       "net/http"
)

func main() {

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.utstamp.com/block/root/{hash}", data)
    req.Header = headers

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


GET https://api.utstamp.com/block/root/{hash} HTTP/1.1
Host: api.utstamp.com

GET /block/root/{hash}

Query the UTStamp block by the root hash. Returns a 404 error if it does not exist.

Parameters

Name In Type Description
hash path string Stamp root hash

Timestamp API

Latest Timestamp

Code samples

require 'rest-client'
require 'json'

result = RestClient.get 'https://api.utstamp.com/timestamp',
  params: {
  }

p JSON.parse(result)


import requests

r = requests.get('https://api.utstamp.com/timestamp')

print(r.json())



fetch('https://api.utstamp.com/timestamp',
{
  method: 'GET'

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


package main

import (
       "bytes"
       "net/http"
)

func main() {

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.utstamp.com/timestamp", data)
    req.Header = headers

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


GET https://api.utstamp.com/timestamp HTTP/1.1
Host: api.utstamp.com

GET /timestamp

Query latest UTStamp timestamp, which is based on Bitcoin and Ethereum. It can cryptographically prove that your current time is after it.

History Timestamp

Code samples

require 'rest-client'
require 'json'

result = RestClient.get 'https://api.utstamp.com/timestamp/epoch/{epoch}',
  params: {
  }

p JSON.parse(result)


import requests

r = requests.get('https://api.utstamp.com/epoch/{epoch}')

print(r.json())


const epoch = 1679279393;
fetch('https://api.utstamp.com/timestamp/epoch/{epoch}',
{
  method: 'GET'

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


package main

import (
       "bytes"
       "net/http"
)

func main() {

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.utstamp.com/timestamp/epoch/{epoch}", data)
    req.Header = headers

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


GET https://api.utstamp.com/timestamp/epoch/{epoch} HTTP/1.1
Host: api.utstamp.com

GET /timestamp/epoch/{epoch}

Query the history timestamp by epoch time in seconds. If it's not exists, a 404 response will be returned.

Parameters

Name In Type Description
epoch path integer epoch in seconds

Code samples

require 'rest-client'
require 'json'

result = RestClient.get 'https://api.utstamp.com/timestamp/stamp_id/{stamp_id}',
  params: {
  }

p JSON.parse(result)


import requests

r = requests.get('https://api.utstamp.com/timestamp/stamp_id/{stamp_id}')

print(r.json())



fetch('https://api.utstamp.com/timestamp/stamp_id/{stamp_id}',
{
  method: 'GET'

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


package main

import (
       "bytes"
       "net/http"
)

func main() {

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.utstamp.com/timestamp/stamp_id/{stamp_id}", data)
    req.Header = headers

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


GET https://api.utstamp.com/timestamp/stamp_id/{stamp_id} HTTP/1.1
Host: api.utstamp.com

GET /timestamp/stamp_id/{stamp_id}

Query history timestamp by stamp id. If it's not exists, a 404 response will be returned.

Parameters

Name In Type Description
stamp_id path string Timestamp id

Code samples

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json'
}

result = RestClient.get 'https://api.utstamp.com/timestamp/mnemonic/{mnemonic}',
  params: {
  }, headers: headers

p JSON.parse(result)


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

r = requests.get('https://api.utstamp.com/timestamp/mnemonic/{mnemonic}', headers = headers)

print(r.json())


const mnemonic = "entry usual regular barrel nothing mail inspire truck enlist push toe peace";
const headers = {
  'Content-Type':'application/json'
};

fetch('https://api.utstamp.com/timestamp/mnemonic/{mnemonic}',
{
  method: 'GET',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});


package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.utstamp.com/timestamp/mnemonic/{mnemonic}", data)
    req.Header = headers

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


GET https://api.utstamp.com/timestamp/mnemonic/{mnemonic} HTTP/1.1
Host: api.utstamp.com
Content-Type: application/json

GET /timestamp/mnemonic/{mnemonic}

Query the history timestamp by BIP39 based mnemonic phrases from stamp_id. If it's not exists, a 404 response will be returned.

Parameters

Name In Type Description
mnemonic path string BIP39 based mnemonic phrases in English
Ruby Python JavaScript GO HTTP