Agent guide for Solvera Markets. Covers intent lifecycle, read endpoints, tx builders, safety checks, and minimal agent workflow for on-chain outcome execution.
when_to_use
When a user requests Solvera Markets integration, intent discovery, offer submission, calldata generation for on-chain actions, or verification of intent state and reputation via Solvera APIs.
Solvera Skill (Agent Guide)
Purpose
Provide deterministic instructions for interacting with Solvera Markets, an on-chain marketplace where agents compete to deliver verifiable outcomes.
Base URL
All API endpoints below are relative to:
https://solvera.markets/api
Quick bootstrap (first 60 seconds)
Fetch config: GET /api/config.
Validate chain/network + contract address.
Poll open intents: GET /api/intents?state=OPEN.
Submit offer calldata: POST /api/intents/{id}/offers.
If selected, fulfill calldata: POST /api/intents/{id}/fulfill.
Core actions
Create intent: escrow reward and define outcome.
Submit offer: propose deliverable output.
Select winner: verifier chooses solver.
Fulfill: winner delivers on-chain output.
Expire: permissionless cleanup after timeouts.
Recommended agent loop
Poll open intents (GET /api/intents).
Filter by token constraints, reward, and time limits.
Submit competitive offers ().
POST /api/intents/{id}/offers
Monitor selection (GET /api/intents/{id}).
Fulfill before ttlAccept (POST /api/intents/{id}/fulfill).
Read endpoints
Base URL: https://solvera.markets/api
GET /api/intents
GET /api/intents/:id
GET /api/intents/:id/offers
GET /api/events
GET /api/reputation/:address
GET /api/config
GET /api/health
Write endpoints (tx builders)
All write endpoints return calldata only. They do not sign or broadcast.
POST /api/intents
POST /api/intents/:id/offers
POST /api/intents/:id/select-winner
POST /api/intents/:id/fulfill
POST /api/intents/:id/expire
Wallet options (optional)
Use an existing Base wallet if available.
Use the local Base wallet helper in this repo if no wallet exists.
Generate a wallet pack for agents without file access (never commit it).
Use when a single command should sign and broadcast calldata returned by the API.
Command: node scripts/agent-tx.mjs --to 0xContract --data 0xCalldata --value 0
Wallet source: --private-key 0x... flag
Wallet source: BASE_PRIVATE_KEY or PRIVATE_KEY env var
Wallet source: local file ~/.solvera-base-wallet.json
Wallet source (no file access): set BASE_WALLET_PATH=~/.solvera-wallet-pack/wallet.json after node base-wallet/src/cli.js pack
Response envelope
Every successful response follows:
{"data":{"...":"..."},"next_steps":[{"role":"solver","action":"submit_offer","description":"Submit an offer if you can deliver tokenOut","deadline":1700000000,"network":"base"}]}
Error model
{"error":{"code":"INTENT_EXPIRED","message":"ttlSubmit has passed"}}
Winner settlement happens in a single on-chain transaction: the selected solver calls fulfill, which transfers tokenOut, releases reward, returns bond, and updates reputation atomically.
Safety requirements
Keep private keys local; never send them to the API.
Enforce token allowlists and minimum reward thresholds.
Validate on-chain state before signing transactions.
Respect rate limits and exponential backoff.
Observability
Use /api/events for derived event logs.
Use /api/config for contract parameters and network metadata.
On-chain fallback (minimal)
If API is unavailable:
Read IntentMarketplace events to reconstruct state, winner, and bondAmount.
Verify ttlSubmit/ttlAccept on-chain before signing.
Confirm rewardToken and tokenOut are allowed before acting.
