oracle-explorer-v2-api.md

Oracle Explorer API

List all announcements

curl  -X GET http://localhost:9000/v2/announcements

This endpoint returns a JSON array of announcement objects.

The announcement object contains following fields:

id - event id

oracleName - name of the oracle

description - event description

uri - event URI (can be null)

announcement - event announcement TLV in hex form

attestations - event attestations in hex form (can be null)

outcome - event outcome (can be null)

Output example

{
  "result": [
    {
      "id": "780410ad590eda01f38ebc0304b08875b1e0bb1dc5c19de7f3578436f109000d",
      "oracleName": "oracle",
      "description": "event",
      "uri": "http://uri",
      "announcement": "fdd82499090fdac1f543cd9698f3a82bd49589d042630649ea1be2ec1242bd6344f8e4b43bd0d6f305a90e149ab1600638750dbf4c59d6d8b4dd877cd0d8f3afd33a8a9e78cf417c9b410873051244fced1e82676f4ca6328ad9e18dcba9d1b04636b0e5fdd822350001342813ce0696df9b1982a1bbf76b8608587fe3582a1b397469b9e12351cefba870dbd880fdd806060002013101320474657374",
      "attestations": "fdd86869047465737478cf417c9b410873051244fced1e82676f4ca6328ad9e18dcba9d1b04636b0e50001342813ce0696df9b1982a1bbf76b8608587fe3582a1b397469b9e12351cefba8a9b939a76cb73153b07e74e6b608094f85e13499ed4b4158d8a2fe7ddaeaefa80131",
      "outcome": "1"
    }
  ],
  "error": null
}

You can specify filters as query string parameters. For example:

curl  -X GET http://localhost:9000/v2/announcements?oracleName=oracle

Currently the API supports only oracleName filter, that allows to filter announcements posted by a specific oracle.

Also you can specify sort order as a query string parameter. For example:

curl  -X GET http://localhost:9000/v2/announcements?sortBy=createdAt

Supported sort orders:

Sort Order	Description
createdAt	Insertion order
createdAt-	Reverse insertion order

By default the API returns 100 latest announcements. To retrieve older ones use page parameter. page value is zero-based page number. Page size is 100 announcements per page.

Get announcement

You'll need an announcement id to perform this call (it's 780410ad590eda01f38ebc0304b08875b1e0bb1dc5c19de7f3578436f109000d in this example).

curl -i -X GET http://localhost:9000/v2/announcements/780410ad590eda01f38ebc0304b08875b1e0bb1dc5c19de7f3578436f109000d

It returns a JSON object of the same type.

HTTP Status:

201 - success 500 - error

Output example

{
  "result": {
    "id": "780410ad590eda01f38ebc0304b08875b1e0bb1dc5c19de7f3578436f109000d",
    "oracleName": "oracle",
    "description": "event",
    "uri": "http://uri",
    "announcement": "fdd82499090fdac1f543cd9698f3a82bd49589d042630649ea1be2ec1242bd6344f8e4b43bd0d6f305a90e149ab1600638750dbf4c59d6d8b4dd877cd0d8f3afd33a8a9e78cf417c9b410873051244fced1e82676f4ca6328ad9e18dcba9d1b04636b0e5fdd822350001342813ce0696df9b1982a1bbf76b8608587fe3582a1b397469b9e12351cefba870dbd880fdd806060002013101320474657374",
    "attestations": null,
    "outcome": null
  },
  "error": null
}

Create an announcement

Submit an HTTP form like this:

curl -i -X POST http://localhost:9000/v2/announcements \
  -F "oracleName=suredbits-oracle-bot" \
  -F "description=event" \
  -F "uri=http://uri"  \
  -F "oracleAnnouncementV0=fdd82499090fdac1f543cd9698f3a82bd49589d042630649ea1be2ec1242bd6344f8e4b43bd0d6f305a90e149ab1600638750dbf4c59d6d8b4dd877cd0d8f3afd33a8a9e78cf417c9b410873051244fced1e82676f4ca6328ad9e18dcba9d1b04636b0e5fdd822350001342813ce0696df9b1982a1bbf76b8608587fe3582a1b397469b9e12351cefba870dbd880fdd806060002013101320474657374"

Form fields:

oracleName - the heman readable name of the oracle

description - the event description

uri - the event URI (optional)

oracleAnnouncementV0 - the oracle announcement (v0) in hex form

The output body contains the event id as a JSON string.

HTTP Status:

201 - success 500 - error

Output example:

{
  "result": "780410ad590eda01f38ebc0304b08875b1e0bb1dc5c19de7f3578436f109000d",
  "error": null
}

Create an announcement's attestation

Use the event id (it's 780410ad590eda01f38ebc0304b08875b1e0bb1dc5c19de7f3578436f109000d for this example), and post the form:

curl -i -X POST http://localhost:9000/v2/announcements/780410ad590eda01f38ebc0304b08875b1e0bb1dc5c19de7f3578436f109000d/attestations \
	-F "attestations=fdd86869047465737478cf417c9b410873051244fced1e82676f4ca6328ad9e18dcba9d1b04636b0e50001342813ce0696df9b1982a1bbf76b8608587fe3582a1b397469b9e12351cefba8a9b939a76cb73153b07e74e6b608094f85e13499ed4b4158d8a2fe7ddaeaefa80131"

where

attestations - the event's attestation in hex form

The output body contains the event metadata as a JSON object.

HTTP Status:

201 - success 500 - error

Output example:

{
  "result": {
    "id": "780410ad590eda01f38ebc0304b08875b1e0bb1dc5c19de7f3578436f109000d",
    "oracleName": "oracle",
    "description": "event",
    "uri": "http://uri",
    "announcement": "fdd82499090fdac1f543cd9698f3a82bd49589d042630649ea1be2ec1242bd6344f8e4b43bd0d6f305a90e149ab1600638750dbf4c59d6d8b4dd877cd0d8f3afd33a8a9e78cf417c9b410873051244fced1e82676f4ca6328ad9e18dcba9d1b04636b0e5fdd822350001342813ce0696df9b1982a1bbf76b8608587fe3582a1b397469b9e12351cefba870dbd880fdd806060002013101320474657374",
    "attestations": "fdd86869047465737478cf417c9b410873051244fced1e82676f4ca6328ad9e18dcba9d1b04636b0e50001342813ce0696df9b1982a1bbf76b8608587fe3582a1b397469b9e12351cefba8a9b939a76cb73153b07e74e6b608094f85e13499ed4b4158d8a2fe7ddaeaefa80131",
    "outcome": "1"
  },
  "error": null
}

Getting an oracle's username

If you have the oracle's public key, you can fetch the username that is registered on oracle explorer. This is useful for desktop clients like krystal bull when submitting events to the oracle explorer

The Schnorr public key (x_point) on the oracle announcement is the parameter in the GET request

curl http://localhost:9000/v2/oracle/1d5dcdba2e64cb116cc0c375a0856298f0058b778f46bfe625ac6576204889e4             {"pubkey":"1d5dcdba2e64cb116cc0c375a0856298f0058b778f46bfe625ac6576204889e4","oracleName":"Chris_Stewart_5"}

Output example:

{
  "result": {
    "pubkey": "1d5dcdba2e64cb116cc0c375a0856298f0058b778f46bfe625ac6576204889e4",
    "oracleName": "Chris_Stewart_5"
  },
  "error": null
}

If the public key is not registered on the oracle explorer, you will get a response of null

curl http://localhost:9000/v2/oracle/e31ede6aa249a0d1efe0977380d6c1ee968c3a796ecdf2a6a45de57d60d4c489

null