Somnia Agents Marketplace Example

This repository contains example implementations for invoking Somnia Agents from:

• Solidity, using a callback-based contract flow
• JavaScript/TypeScript, using direct request submission and response reads

The example app is a marketplace for new and used goods where an agent reviews a listing price and classifies it as:

• cheaper
• normal
• overpriced

Overview

The example is built around Somnia's ExtractString agent method.

The core flow is:

1. A user creates a marketplace listing.
2. The app submits an agent request to review the listing price against a trusted marketplace source.
3. The request is linked to the listing with requestId.
4. Once the agent response is confirmed, the listing is updated with the final assessment.

The Solidity example uses a platform callback. The Node example shows direct agent invocation from TypeScript.

Platform Details

• Platform contract: 0x037Bb9C718F3f7fe5eCBDB0b600D607b52706776
• Agent ID: 12875401142070969085

Repository Structure

• contracts/ Hardhat workspace for Solidity contracts and deployment scripts.
• node/ TypeScript workspace for direct agent invocation examples.
• frontend/ Placeholder frontend workspace.

Solidity Example

Main contract:

• contracts/contracts/Sample.sol

Reusable modules:

• contracts/contracts/types/AgentTypes.sol
• contracts/contracts/interfaces/IAgent.sol
• contracts/contracts/interfaces/IAgentRequester.sol
• contracts/contracts/interfaces/IERC20.sol
• contracts/contracts/libraries/AgentCodec.sol

What the contract does

The marketplace contract:

• creates listings for New and Used items
• settles purchases in USDC
• submits a price-review request to a Somnia Agent
• links requestId to listingId
• updates the listing in the callback once the platform confirms the result

Marketplace source selection

To reduce seller-controlled price manipulation, the contract does not accept a custom marketplace URL from the seller.

Instead, it selects a trusted source by category:

• electronics, phones, laptops, gaming -> Swappa
• instruments, music, guitars -> Reverb Price Guide
• sneakers, streetwear -> StockX
• everything else -> eBay completed listings

Contract invocation flow

1. createListing(...) stores the listing.
2. requestListingReview(...) builds an ExtractString payload.
3. The contract calls createRequest(...) on the Somnia platform.
4. requestId is mapped to listingId.
5. handleResponse(...) decodes the first string result and updates the listing assessment.

USDC pricing

Listing prices are expected in USDC base units.

Examples:

• 1 USDC -> 1_000000
• 25 USDC -> 25_000000
• 450 USDC -> 450_000000

The Somnia request deposit is still paid in the chain's native token.

JavaScript / TypeScript Example

Main files:

• node/src/index.ts
• node/src/web.ts
• node/src/config.ts

What the Node example does

The TypeScript example:

• encodes an ExtractString request
• calculates the required deposit
• sends a request to the platform contract
• waits for RequestCreated
• waits for RequestFinalized
• reads and decodes the response

Current example invocation

The current example in node/src/index.ts checks a used electronics listing against Swappa.

It submits a request roughly equivalent to:

await invokeWebAgent(
  "price_assessment",
  "Classify whether the listing price is cheaper, normal, or overpriced compared to similar used marketplace listings.",
  ["cheaper", "normal", "overpriced"],
  "Review this used electronics listing: 'Used iPhone 13 128GB'. The seller is asking 450000000 USDC base units (450 USDC). Compare it against similar offers on the marketplace page and return exactly one of: cheaper, normal, overpriced.",
  "https://swappa.com/buy/phones",
  true,
  1,
  80,
)

JavaScript invocation flow

1. Encode the ExtractString payload.
2. Read getRequestDeposit().
3. Add execution budget on top of the reserve.
4. Submit createRequest(...).
5. Wait for RequestCreated.
6. Wait for RequestFinalized.
7. Read the request state and decode the successful response.

Setup

Contracts workspace

cd contracts
npm install

Useful commands:

npx hardhat test
npx hardhat run scripts/deploy-marketplace.ts --network <network> -- <usdc-token-address>

Deployment script:

• contracts/scripts/deploy-marketplace.ts

Node workspace

cd node
npm install
cp .env.example .env

Set PRIVATE_KEY in .env.

Useful commands:

npm run typecheck
npm run build
npm start

Notes

• The Node example currently demonstrates direct invocation and response handling outside the Solidity callback flow.
• The Solidity example is better for agent-driven application design where request confirmation should update onchain state automatically.
• The reusable Solidity types, interfaces, and codec library are intended to make future agent-powered contracts easier to build.

Next Steps

• add frontend listing and review UI
• add contract tests for callback flows
• add network-specific deployment notes
• expand the examples into a full production application