The Reality Keys API

API | Resources

We provide an API allowing anyone to create Reality Keys for facts, and check on the status of existing Reality Keys.

See our resources page for some tools and examples for how you might use the API.

Our API is accessible free of charge, without the need for authentication. We suggest, but do not require, that you include an email address in the user-agent header that will allow us to contact you if there is a problem. If you plan to use our service heavily or for a mission-critical purpose, we suggest you let us know in advance to make sure we're ready for you.

Our API supplies CORS headers, so it can be accessed using JavaScript without using JSONP.

You can ask us to serve either facts, resolving to true/false, or data values.
If you specify a comparison we will provide keys. If you omit the comparison, we will provide a signed value.

Exchange Rates

We can track exchange rates between traditional currencies, crypto-currencies and combinations of both.

Creating Reality Keys for an exchange rate

Send a POST request to:
https://www.realitykeys.com/api/v1/exchange/new

Include the following fields:

  • fromcur The currency to convert from XBT
  • comparison ge for greater-than-or-equal-to or lt for less-than ge
  • tocur The currency to convert to USD
  • value The value to compare against 1000
  • settlement_date The date (UTC) when the answer should be checked. 2015-09-23
  • objection_period_secs The time in seconds to wait for an objection. 604800
  • accept_terms_of_service The version of the Terms of Service you accept, or "current" for the current Terms of Service. current
  • use_existing Use existing keys if they match the conditions you set. 1

Example using wget


On success, we will return a JSON object containing the details of the fact that you have created, identical to the response you should now get if you call the "checking on an existing Reality Key" GET request with the ID of the fact you have created.

Checking on an existing Reality Key

Send a GET request to:
https://www.realitykeys.com/api/v1/exchange/<id>?accept_terms_of_service=current eg:
https://www.realitykeys.com/api/v1/exchange/1?accept_terms_of_service=current

This will return a 200 response containing a single JSON object with the details of your fact, or a 404 response if the fact could not be found.

Blockchain addresses

We can check the amount of money in a given address. We currently use blockr.io. This may change in future if these services become unavailable or unreliable.

Creating a Reality Key about a blockchain address

Send a POST request to:
https://www.realitykeys.com/api/v1/blockchain/new

Include the following fields:

  • chain The name of the chain or alt-coin you want to monitor.
    Use XBT for the main Bitcoin chain.
    Other chains should be as listed on blockr.io.
    XBT
  • address The address to monitor, if monitoring an address 1F1tAaz5x1HUXrCNLbtMDqcw6o5GNn4xqX
  • which_total total_received or final_balance, if monitoring an address.
    difficulty for blockchain difficulty
    total_received
  • comparison ge for greater-than-or-equal-to or lt for less-than ge
  • valueThe value to compare against. 1000
  • settlement_date The date (UTC) when the answer should be checked. 2015-09-23
  • objection_period_secs The time in seconds to wait for an objection. 604800
  • accept_terms_of_service The version of the Terms of Service you accept, or "current" for the current Terms of Service. current
  • use_existing Use existing keys if they match the conditions you set. 1

Example using wget


On success, we will return a JSON object containing the details of the fact that you have created, identical to the response you should now get if you call the "checking an existing Reality Key" GET request with the ID of the fact you have created.

Checking an existing Reality Key

Send a GET request to:
https://www.realitykeys.com/api/v1/blockchain/<id> eg:
https://www.realitykeys.com/api/v1/blockchain/2?accept_terms_of_service=current

This will return a 200 response containing a single JSON object with the details of your fact, or a 404 response if the fact could not be found.

Freebase

Freebase has been deprecated by Google. You can no longer register new Freebase facts with us, although you can still query existing ones.

Please use our WikiData API instead.

Reality Keys handles three different patterns. The appropriate pattern will depend on how the data you want to query is structured in Freebase.


Node-attribute-node

Node 1 Attribute 1 Node 2

Barack Obama Gender Male

Node-attribute-comparison-property

Node 1 Attribute 1 Comparison Value 1

Barack Obama Weight (kg) At least 80

Node-attribute-node-attribute

This is needed for relationships between nodes that Freebase manages as "compound value types", using an intermediate node that can hold information about the relationship between the two nodes.

Node 1 Attribute 1  ?  Attribute 2 Node 2

Barack Obama Offices Held  ?  Office Holders President of the United States

The fact is deemed to be true if a common connection is found between the list found in Node 1 Attribute 1 and that found in Node 2 Attribute 2.


Creating a Reality Key about something in Freebase

Node-attribute-node

Send a POST request to:

https://www.realitykeys.com/api/v1/freebase/new
  • node1_id The ID in Freebase of the main node. /en/barack_obama
  • node1_attribute_id The property of Node 1 that relates it to Node 2. /people/person/gender
  • node2_id The ID in Freebase of the other node. /m/05zppz
  • settlement_date The date (UTC) when the answer should be checked. 2015-09-23
  • objection_period_secs The time in seconds to wait for an objection. 604800
  • accept_terms_of_service The version of the Terms of Service you accept, or "current" for the current Terms of Service. current
  • use_existing Use existing keys if they match the conditions you set. 1

Example using wget


Node-attribute-comparison-property

Send a POST request to:

https://www.realitykeys.com/api/v1/freebase/new
  • node1_id The ID in Freebase of the main node. /en/barack_obama
  • node1_attribute_id The property of Node 1 that relates it to Node 2. /people/person/weight_kg
  • comparison The way to compare the property and the defined value ge
  • node1_attribute_value A literal value of the property. 80
  • settlement_date The date (UTC) when the answer should be checked. 2015-09-23
  • objection_period_secs The time in seconds to wait for an objection. 604800
  • accept_terms_of_service The version of the Terms of Service you accept, or "current" for the current Terms of Service. current

Example using wget


Node-attribute-node-attribute

Send a POST request to:

https://www.realitykeys.com/api/v1/freebase/new
  • node1_id The ID in Freebase of the main node. /en/barack_obama
  • node1_attribute_id The property of Node 1 that relates it to Node 2. /government/politician/government_positions_held
  • node2_id The ID in Freebase of the other node. /en/president_of_the_united_states
  • node2_attribute_id The property of Node 2 that relates it to Node 1. /government/government_office_or_title/office_holders
  • settlement_date The date (UTC) when the answer should be checked. 2015-09-23
  • objection_period_secs The time in seconds to wait for an objection. 604800
  • accept_terms_of_service The version of the Terms of Service you accept, or "current" for the current Terms of Service. current
  • use_existing Use existing keys if they match the conditions you set. 1

Example using wget


On success, we will return a JSON object containing the details of the fact that you have created, identical to the response you should now get if you call the "checking an existing Reality Key" GET request with the ID of the fact you have created.

Checking an existing Reality Key

Send a GET request to:
https://www.realitykeys.com/api/v1/freebase/<id> eg
https://www.realitykeys.com/api/v1/freebase/3?accept_terms_of_service=current

This will return a 200 response containing a single JSON object with the details of your fact, or a 404 response if the fact could not be found.

Soccer Results

We check Premium League soccer results using the data at football-api.com. This may change in future if these services become unavailable or unreliable.

Creating a Reality Key about a soccer result

Send a POST request to:
https://www.realitykeys.com/api/v1/soccer/new

Include the following fields:

  • football_api_match_id The ID of the match in football-api.com 1940587
  • football_api_team1_id Team 1 (conventionally the home team) using its ID in football-api.com 9002
  • football_api_team2_id Team 2 (conventionally the away team) using its ID in football-api.com 9406
  • comparison The score of team1 compared to the score of team2. gt, lt, ge, le or eq for win, lose, win-or-draw, lose-or-draw or draw gt
  • settlement_date The date-time (UTC) when the answer should be checked.
    This would normally be set to the scheduled end time of the match.
    2014-09-27
  • objection_period_secs The time in seconds to wait for an objection. 604800
  • accept_terms_of_service The version of the Terms of Service you accept, or "current" for the current Terms of Service. current
  • use_existing Use existing keys if they match the conditions you set. 1

Example using wget


On success, we will return a JSON object containing the details of the fact that you have created, identical to the response you should now get if you call the "checking an existing Reality Key" GET request with the ID of the fact you have created.

Checking an existing Reality Key

Send a GET request to:
https://www.realitykeys.com/api/v1/soccer/<id> eg:
https://www.realitykeys.com/api/v1/soccer/2?accept_terms_of_service=current

This will return a 200 response containing a single JSON object with the details of your fact, or a 404 response if the fact could not be found.

RunKeeper

We can track exercise achievements on RunKeeper.

Creating Reality Keys for a RunKeeper exercise

Send a POST request to:
https://www.realitykeys.com/api/v1/runkeeper/new

Include the following fields:

Example using wget


On success, we will return a JSON object containing the details of the fact that you have created, identical to the response you should now get if you call the "checking on an existing Reality Key" GET request with the ID of the fact you have created.

Checking on an existing Reality Key

Send a GET request to:
https://www.realitykeys.com/api/v1/runkeeper/<id>?accept_terms_of_service=current eg:
https://www.realitykeys.com/api/v1/runkeeper/1?accept_terms_of_service=current

This will return a 200 response containing a single JSON object with the details of your fact, or a 404 response if the fact could not be found.

WikiData

Creating a Reality Key about something in WikiData

Send a POST request to:

https://www.realitykeys.com/api/v1/wikidata/new

Example using wget

On success, we will return a JSON object containing the details of the fact that you have created, identical to the response you should now get if you call the "checking an existing Reality Key" GET request with the ID of the fact you have created.

Checking an existing Reality Key

Send a GET request to:
https://www.realitykeys.com/api/v1/wikidata/<id> eg
https://www.realitykeys.com/api/v1/wikidata/3290?accept_terms_of_service=current

This will return a 200 response containing a single JSON object with the details of your fact, or a 404 response if the fact could not be found.

Human-verified data

Creating a Reality Key about an arbitrary proposition that you have already cleared with us

Sometimes people ask us to certify facts that we can't fetch from an API.

Send a POST request to:

https://www.realitykeys.com/api/v1/human/new

Example using wget

On success, we will return a JSON object containing the details of the fact that you have created, identical to the response you should now get if you call the "checking an existing Reality Key" GET request with the ID of the fact you have created.

Checking an existing Reality Key

Send a GET request to:
https://www.realitykeys.com/api/v1/human/<id> eg
https://www.realitykeys.com/api/v1/human/3290?accept_terms_of_service=current

This will return a 200 response containing a single JSON object with the details of your fact, or a 404 response if the fact could not be found.