Somnia Oracle

Somnia Oracle

Resolve real-world questions onchain. Committees of Somnia Agents read the sources a question names and publish one immutable answer, with receipts, in minutes.

Somnia Oracle resolves questions about the real world onchain. You submit a question, the sources that answer it and the time it should resolve. At that time, committees of Somnia Agents read each website and API, contract sources are read directly, and the oracle aggregates the results into a single answer that any contract can read.

It is a general-purpose question oracle, not a price feed. Prices are one kind of question it answers, alongside sports results, elections, economic releases, weather, social metrics and anything else a public source reports.

Why Somnia Oracle

  • Minutes, not days. Agents answer at resolution time and aggregation happens onchain. There is no human arbitration round and no dispute window.
  • Auditable. Every answer carries a receipt for each source that was read, and each agent's step-by-step execution log is public.
  • Any question with a public answer. Discrete outcomes (a fixed list of labels) and numeric intervals cover far more than prices.
  • No keepers. Somnia Reactivity triggers resolution onchain, so there is no off-chain bot that must stay online. If a trigger is ever missed, anyone can fire it.
  • Pay per question. Fees are paid in the native token with the submission. There are no subscriptions or ERC-20 approvals.

How a question resolves

  1. Submit. You call submitQuestion on the OracleEntryPoint with a QuestionDefinition and the fee. The definition holds the question text, 1 to 20 sources, the valid answers, the resolution time and the agreement rules. The call returns the questionId.
  2. Moderate and name. In the same transaction, a moderation committee reviews the question and a naming committee writes a short display name. Both are advisory: a Rejected verdict does not stop the question resolving.
  3. Wait. OracleCore subscribes to Somnia Reactivity for the question's resolutionTime.
  4. Dispatch. At resolutionTime, Reactivity wakes OracleCore. Each Website and JSON source goes to its own agent subcommittee (3 agents by default, 2 of which must agree). Contract sources are read with a staticcall in the same transaction.
  5. Aggregate. When every source has reported, OracleCore takes the median across sources for numeric questions or the majority label for discrete ones, and posts one immutable Answer. If too few sources agree, the question is voided with a reason instead.
  6. Read. Contracts pull the answer with getAnswer(questionId). Off-chain consumers can watch the AnswerPosted or AnswerFinalized events.

Answers are terminal. Once posted, an answer can never change. Consumers that need a dispute process, such as prediction markets, build it on top.

Networks and contracts

The oracle runs on Somnia Mainnet and Somnia Testnet, at the same addresses on both.

Property Mainnet Testnet
Chain ID 5031 50312
RPC URL https://api.infra.mainnet.somnia.network https://api.infra.testnet.somnia.network
Currency SOMI STT
OracleEntryPoint 0x5D7AA25129FD7a3712fd11e4FaEeE9034c2aC2AB 0x5D7AA25129FD7a3712fd11e4FaEeE9034c2aC2AB
OracleCore 0x463711Ab0C84Bdf9faf1925162885ACA74ed95a9 0x463711Ab0C84Bdf9faf1925162885ACA74ed95a9
QuestionModerationRegistry 0xd60777eC9fd3e1B1C2af5964127CC01Beb8E16Ac 0xd60777eC9fd3e1B1C2af5964127CC01Beb8E16Ac
QuestionNameRegistry 0xBe8a94Ca55cF8d4B2fbF1E66fe86c65238c78382 0xBe8a94Ca55cF8d4B2fbF1E66fe86c65238c78382
Indexer (GraphQL) https://prd.oracle.somnia.host/v1/graphql https://dev.oracle.somnia.host/v1/graphql

OracleEntryPoint is the only contract you need to call. It takes submissions, splits the fee between the other three contracts, and routes every read to the right OracleCore. All four contracts are UUPS proxies, so these addresses stay fixed across upgrades.

The indexer is a public GraphQL endpoint over every question, source, agent request and answer. It needs no key.

Explore questions

The Somnia Explorer shows every question, its sources, each agent's response and the final answer. You can also start a question from a template there and submit it from your wallet. Use the chain selector to switch between Global (mainnet) and Global testnet. See Using the explorer for a tour.

Next steps

  • Asking questions: write questions that resolve cleanly, pick an answer type and set the agreement rules.
  • From Solidity: submit a question and consume its answer from a contract, or from TypeScript with viem.
  • Sources: the three source types and how to encode each one.
  • Ratings: Caliber's quality grade for every question.
  • Using the explorer: the oracle pages in the Somnia Explorer.

Edit this page