JSON API Request
JSON API Request
A Somnia Agents base agent that fetches JSON from any public API and returns one value from it, picked by a selector path, to your contract.
JSON API Request is a base agent on Somnia Agents. A contract names a URL and a selector path such as data.price or items[0].name; a subcommittee of validators fetches the JSON, picks the value, agrees on it and returns it to the contract's callback. It is the building block for an onchain oracle on any public API.
How a request runs
- The contract encodes one of the agent's methods, with the URL, the selector and, for a number, the decimals to scale it by, and submits it as a request through the agents platform's
createRequest. - Each validator in the subcommittee fetches the URL and extracts the value at the selector.
- The validators' responses and a status are returned to the contract's callback, with a receipt; the contract reads the agreed value from them.
Numbers are scaled by 10 to the power of decimals so a floating-point value from an API becomes an integer a contract can use: with 8 decimals, 42000.50 becomes 4200050000000.
Methods
| Method | Returns | For |
|---|---|---|
fetchString |
string |
Names, text values |
fetchUint |
uint256 |
Prices, positive numbers |
fetchInt |
int256 |
Signed numbers |
fetchBool |
bool |
Flags, status checks |
fetchStringArray |
string[] |
Lists of names or ids |
fetchUintArray |
uint256[] |
Price lists, numeric arrays |
Reference
Parameters, selector syntax, the price per subcommittee member and examples are in the agent's reference page, JSON API Request. Calling any agent from Solidity is in Invoking from Solidity.
For a median token price across exchanges, with no API to pick, use Price Oracle. For a page that is HTML rather than JSON, use LLM Parse Website.
Every registered agent, with its methods and price, is in the Agents directory in the Somnia Explorer.