Skip to content

Gateway HTTP API

Jump to bottom
Jacob Henderson edited this page Feb 20, 2020 · 1 revision

A Chainpoint Gateway exposes a public HTTP API that can:

  • accept new hashes
  • retrieve proofs with a hash ID
  • verify proofs
  • provide configuration and audit info
  • provide verified calendar info

API Documentation

The Gateway HTTP API has been documented using Swagger: chainpoint-gateway-openapi-3.yaml

API Examples

The output of the curl samples provided here have been 'pretty printed' with the excellent jq tool for easier readability. You can strip off the | jq portion of most of the example commands if you don't wish to install or use it.

Submitting Hash(es)

Submit a single hash, or an Array of hashes at once using the POST /hashes API passing in a JSON body. The hashes property must be represented as an Array of Hexadecimal strings. You must submit at least 1, and no more than 1,000, hashes at a time. The HTTP response will include some useful meta information, and most importantly, a proof-id value which is a Version 1 UUID that can be used to retrieve a proof later.

curl -s -X POST http://35.230.179.171/hashes -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"hashes": ["1957db7fe23e4be1740ddeb941ddda7ae0a6b782e536a9e00b5aa82db1e84547"]}' | jq

{
  "meta": {
    "submitted_at": "2018-07-23T04:01:52Z",
    "processing_hints": {
      "cal": "2018-07-23T04:02:07Z",
      "btc": "2018-07-23T06:00:00Z"
    }
  },
  "hashes": [
    {
      "proof_id": "21e44280-8e2d-11e8-8690-0112cb9597ab",
      "hash": "1957db7fe23e4be1740ddeb941ddda7ae0a6b782e536a9e00b5aa82db1e84547"
    }
  ]
}

Retrieving Proof(s)

You can retrieve 1, or as many as 1,000, proofs in a single request to the GET /proofs or GET /proofs/:proof_id API endpoints. The proof_id value is the one provided in response to submitting a hash.

You can request a Chainpoint Proof for a specific proof_id by passing it in as an argument in the path of the GET request.

curl -s -X GET http://35.230.179.171/proofs/21e44280-8e2d-11e8-8690-0112cb9597ab

Alternatively, you can send a proofids request header composed of a String of comma separated proof_id values.

curl -s -X GET http://35.230.179.171/proofs -H 'proofids: 21e44280-8e2d-11e8-8690-0112cb9597ab,33f81c40-8e31-11e8-8690-0147b5e52019'

When you make a request for a Chainpoint Proof it can be returned in one of two possible formats. A JSON-LD Object, or a String of Base64 encoded binary data. These forms are described in more detail in the Chainpoint binary repository. You can choose which format the Gateway API will return by passing an appropriate Accept header with your request. The default, as it is smaller to send over the wire, is Base64 encoded binary.

Default (Base64)

curl -s -X GET http://35.230.179.171/proofs/21e44280-8e2d-11e8-8690-0112cb9597ab | jq
[
  {
    "proof_id": "21e44280-8e2d-11e8-8690-0112cb9597ab",
    "proof": "eJyNU0tuE0EQ5QgcgiWOq/rfs4rEFVixsaq6qvFIwbY8w28Z2LAkRwgJSkBskBBL7mGJw9B2PkCiCFaj6e736r1XVe/O98tyMeqr8cd8HFdDN52+tL3sLddPp2VO/WK17Bfj9IU9HV+v9POj66PTOQ3zzT5mH4VjVWPVsWJ0IKKcHYoIRVKgwDEZ9TZQVgD2RMkIoybnXfyypZn1MlssRTcPDKpzJsEkqZEJtkeTFDJMANEUzj5H4u87yPCcn/XjqBfIGY3fDGCaQJwY+xhcB9h58+SavizXO/oavfd/0rMxrtF7QFuSDanepN8i76I/5zUtylyHozcfD4j14Guhg9n2aLmeXdydLFfDz3v3D48PNg93Snvp/sfl4Yfl6myY08T4sAPvdOzA//ZwE/x+0Q9jh94ai8kBdLHWIGBy9cb5UrUKRlMq+2JMrCa4GL0TMcU1BmtVMwaVxi6piDprIvjisVrMDKHVRBYrkEADYZNBLteoZfvNjCWwDbFoMgFdoFTLTYH7bLkNiVrNtplBaxtQE9Vago/F15jFJirqQLn9RyyCKbnkOCJzlluEzSVyZikugjYj2aL3qc2iVCUomUgckXXgY4g+iYNtlJyhdUCB821C1hZDrcYaUvRM1oOoD4Y4ZsdFqIXLzV0iUQO2CQu5aSRn2iKEWz1pd4AhuKu2eAwddldLWPZ+b992Gbs2WN0l4vB4vdm3QbkFrzlVyyLZVbAgAIk9cFSK2PJrQbY2UetBixY5xtJCUAvVu7/knF2M7HD0drfmJ63Yp8sp7uXssuzp83U/HG327pI4bShdCK2nl4DpdpN+AbZKagM=",
    "anchors_complete": [
      "cal"
    ]
  }
]

Explicit (Base64)

curl -s -X GET http://35.230.179.171/proofs/21e44280-8e2d-11e8-8690-0112cb9597ab -H 'Accept: application/vnd.chainpoint.json+base64' | jq
[
  {
    "proof_id": "21e44280-8e2d-11e8-8690-0112cb9597ab",
    "proof": "eJyNU0tuE0EQ5QgcgiWOq/rfs4rEFVixsaq6qvFIwbY8w28Z2LAkRwgJSkBskBBL7mGJw9B2PkCiCFaj6e736r1XVe/O98tyMeqr8cd8HFdDN52+tL3sLddPp2VO/WK17Bfj9IU9HV+v9POj66PTOQ3zzT5mH4VjVWPVsWJ0IKKcHYoIRVKgwDEZ9TZQVgD2RMkIoybnXfyypZn1MlssRTcPDKpzJsEkqZEJtkeTFDJMANEUzj5H4u87yPCcn/XjqBfIGY3fDGCaQJwY+xhcB9h58+SavizXO/oavfd/0rMxrtF7QFuSDanepN8i76I/5zUtylyHozcfD4j14Guhg9n2aLmeXdydLFfDz3v3D48PNg93Snvp/sfl4Yfl6myY08T4sAPvdOzA//ZwE/x+0Q9jh94ai8kBdLHWIGBy9cb5UrUKRlMq+2JMrCa4GL0TMcU1BmtVMwaVxi6piDprIvjisVrMDKHVRBYrkEADYZNBLteoZfvNjCWwDbFoMgFdoFTLTYH7bLkNiVrNtplBaxtQE9Vago/F15jFJirqQLn9RyyCKbnkOCJzlluEzSVyZikugjYj2aL3qc2iVCUomUgckXXgY4g+iYNtlJyhdUCB821C1hZDrcYaUvRM1oOoD4Y4ZsdFqIXLzV0iUQO2CQu5aSRn2iKEWz1pd4AhuKu2eAwddldLWPZ+b992Gbs2WN0l4vB4vdm3QbkFrzlVyyLZVbAgAIk9cFSK2PJrQbY2UetBixY5xtJCUAvVu7/knF2M7HD0drfmJ63Yp8sp7uXssuzp83U/HG327pI4bShdCK2nl4DpdpN+AbZKagM=",
    "anchors_complete": [
      "cal"
    ]
  }
]

Explicit (JSON-LD)

curl -s -X GET http://35.230.179.171/proofs/5e0433d0-46da-11ea-a79e-017f1945257 -H 'Accept: application/vnd.chainpoint.ld+json' | jq
{
  "@context": "https://w3id.org/chainpoint/v4",
  "type": "Chainpoint",
  "hash": "ffff27222fe366d0b8988b7312c6ba60ee422418d92b62cdcb71fe2991ee7391",
  "proof_id": "5e0433d0-46da-11ea-a79e-017f1945257",
  "hash_received": "2020-02-03T23:10:28Z",
  "branches": [
    {
      "label": "aggregator",
      "ops": [],
      "branches": [
        {
          "label": "cal_anchor_branch",
          "ops": [
            {
              "l": "nistv2:1580771400:d5aa7ffdada5f6b9c6743ffd245c1d2b2ca32c68eca35576181c882f77cecda3a304d8ea4f9a0293831095187f6b5a0bfda1bd79d93da2badd45edf406b5691d"
            },
            {
              "op": "sha-256"
            },
            {
              "anchors": [
                {
                  "type": "tcal",
                  "anchor_id": "7159fe850b6ddb51ff50dc4d44b1aa363128e52ad49f21fd68b1cd0c77afa64d",
                  "uris": [       "http://3.135.54.225/calendar/7159fe850b6ddb51ff50dc4d44b1aa363128e52ad49f21fd68b1cd0c77afa64d/data"
                  ]
                }
              ]
            }
          ],
          "branches":[]
        }
      ]
    }
  ]
}

The HTTP response will contain a JSON wrapper around the Chainpoint Proof(s) that are returned. It is important to note that this return value is not the Proof, it is a wrapper containing an Array of one or more Objects, each of which have a proof property which is the actual Chainpoint Proof. This return format not only allows us to return multiple proofs at once, it also allows you to determine (without parsing the proof) which anchors each proof contains (e.g. cal or cal, btc). You must extract the Proof itself from this return structure before you pass it to the POST /verify step documented below.

[
  {
    "proof_id": "21e44280-8e2d-11e8-8690-0112cb9597ab",
    "proof": "THE_PROOF_WILL_BE_FOUND_HERE",
    "anchors_complete": [
      "cal"
    ]
  }
]

Pro Tip: If testing with curl you can extract just the proof from the return structure using | jq '.[0].proof'. There are more examples of how to use jq here.

curl -s -X GET http://35.230.179.171/proofs/21e44280-8e2d-11e8-8690-0112cb9597ab | jq '.[0].proof'
"eJyNU0tuE0EQ5QgcgiWOq/rfs4rEFVixsaq6qvFIwbY8w28Z2LAkRwgJSkBskBBL7mGJw9B2PkCiCFaj6e736r1XVe/O98tyMeqr8cd8HFdDN52+tL3sLddPp2VO/WK17Bfj9IU9HV+v9POj66PTOQ3zzT5mH4VjVWPVsWJ0IKKcHYoIRVKgwDEZ9TZQVgD2RMkIoybnXfyypZn1MlssRTcPDKpzJsEkqZEJtkeTFDJMANEUzj5H4u87yPCcn/XjqBfIGY3fDGCaQJwY+xhcB9h58+SavizXO/oavfd/0rMxrtF7QFuSDanepN8i76I/5zUtylyHozcfD4j14Guhg9n2aLmeXdydLFfDz3v3D48PNg93Snvp/sfl4Yfl6myY08T4sAPvdOzA//ZwE/x+0Q9jh94ai8kBdLHWIGBy9cb5UrUKRlMq+2JMrCa4GL0TMcU1BmtVMwaVxi6piDprIvjisVrMDKHVRBYrkEADYZNBLteoZfvNjCWwDbFoMgFdoFTLTYH7bLkNiVrNtplBaxtQE9Vago/F15jFJirqQLn9RyyCKbnkOCJzlluEzSVyZikugjYj2aL3qc2iVCUomUgckXXgY4g+iYNtlJyhdUCB821C1hZDrcYaUvRM1oOoD4Y4ZsdFqIXLzV0iUQO2CQu5aSRn2iKEWz1pd4AhuKu2eAwddldLWPZ+b992Gbs2WN0l4vB4vdm3QbkFrzlVyyLZVbAgAIk9cFSK2PJrQbY2UetBixY5xtJCUAvVu7/knF2M7HD0drfmJ63Yp8sp7uXssuzp83U/HG327pI4bShdCK2nl4DpdpN+AbZKagM="

Verify Proof(s)

You can verify a proof by passing it to the Gateway's POST /verify endpoint, or if desired by performing your own validation against a copy of the Bitcoin blockchain.

To verify using a Gateway, pass in the proof output from the previous step to the POST /verify endpoint. This endpoint expects a JSON POST body containing a JSON Object with a proofs property which is an Array of Chainpoint proofs in either Base64 encoded binary, or JSON-LD`.

Submit that proof as part of the proofs Array to verify it:

curl -s -X POST \
http://35.230.179.171/verify \
-H 'Content-Type: application/json' \
-d '{"proofs": ["BASE64_PROOF_STRING_GOES_HERE"]}' | jq

Base64 Example:

curl -s -X POST \
http://35.230.179.171/verify \
-H 'Content-Type: application/json' \
-d '{"proofs": ["eJyNU0tuE0EQ5QgcgiWOq/rfs4rEFVixsaq6qvFIwbY8w28Z2LAkRwgJSkBskBBL7mGJw9B2PkCiCFaj6e736r1XVe/O98tyMeqr8cd8HFdDN52+tL3sLddPp2VO/WK17Bfj9IU9HV+v9POj66PTOQ3zzT5mH4VjVWPVsWJ0IKKcHYoIRVKgwDEZ9TZQVgD2RMkIoybnXfyypZn1MlssRTcPDKpzJsEkqZEJtkeTFDJMANEUzj5H4u87yPCcn/XjqBfIGY3fDGCaQJwY+xhcB9h58+SavizXO/oavfd/0rMxrtF7QFuSDanepN8i76I/5zUtylyHozcfD4j14Guhg9n2aLmeXdydLFfDz3v3D48PNg93Snvp/sfl4Yfl6myY08T4sAPvdOzA//ZwE/x+0Q9jh94ai8kBdLHWIGBy9cb5UrUKRlMq+2JMrCa4GL0TMcU1BmtVMwaVxi6piDprIvjisVrMDKHVRBYrkEADYZNBLteoZfvNjCWwDbFoMgFdoFTLTYH7bLkNiVrNtplBaxtQE9Vago/F15jFJirqQLn9RyyCKbnkOCJzlluEzSVyZikugjYj2aL3qc2iVCUomUgckXXgY4g+iYNtlJyhdUCB821C1hZDrcYaUvRM1oOoD4Y4ZsdFqIXLzV0iUQO2CQu5aSRn2iKEWz1pd4AhuKu2eAwddldLWPZ+b992Gbs2WN0l4vB4vdm3QbkFrzlVyyLZVbAgAIk9cFSK2PJrQbY2UetBixY5xtJCUAvVu7/knF2M7HD0drfmJ63Yp8sp7uXssuzp83U/HG327pI4bShdCK2nl4DpdpN+AbZKagM="]}' | jq

The response from a POST /verify request will contain metadata about the verification status of each Chainpoint Proof provided including the anchors present in each proof and whether or not the Proof is considered valid when compared to the Calendar URI.

Verify Response Example:

[
  {
    "proof_index": 0,
    "hash": "1957db7fe23e4be1740ddeb941ddda7ae0a6b782e536a9e00b5aa82db1e84547",
    "hash_core": "21e44280-8e2d-11e8-8690-0112cb9597ab",
    "hash_received": "2018-07-23T04:01:52Z",
    "anchors": [
      {
        "branch": "cal_anchor_branch",
        "type": "cal",
        "valid": true
      }
    ],
    "status": "verified"
  }
]
Clone this wiki locally