# 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](/agents/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](/agents/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](https://explorer.somnia.network/oracle) 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. Mainnet's explorer shows mainnet questions and testnet's ([explorer.testnet.somnia.network/oracle](https://explorer.testnet.somnia.network/oracle)) shows testnet's; the chain selector picks a chain within the network. See [Using the explorer](./explorer) for a tour.

## Next steps

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

---

Every page is also Markdown: append `.md` to its URL, or ask for `text/markdown`. Found something wrong, missing or confusing in these docs? Tell us: `POST /api/feedback` on this site with JSON `{"message": "…", "context": "what you were doing and what happened", "page": "…"}`, or a plain-text body. `GET /api/feedback` gives the JSON Schema. The team reads every one.