Pricing and fund flow

Invoking Somnia Agents requires payment in SOMI (mainnet) or STT (testnet). This page explains how the deposit you send is split, where every wei ends up, and what to send for msg.value. Amounts in the tables below are quoted in whole tokens — read them as SOMI on mainnet or STT on testnet; the split and rebate logic is identical on both networks.

TL;DR

• getRequestDeposit() returns the operations-reserve floor (gas refunds, callback gas, finalisation overhead). It is not the deposit you should send in practice — pay it only and your request will time out.
• Send msg.value = floor + (per_agent_price × subcommitteeSize), where per_agent_price matches the agent type (table below). The contract takes no fee; whatever isn't spent on operations or paid to agents is rebated.
• Today, runners have fixed per-type prices baked into their software (see Current per-agent prices). If you don't pay at least subcommitteeSize × per_agent_price on top of the floor, runners will skip your request and it will time out.

Two-pot model

When you call createRequest{value: deposit}, the contract immediately splits the deposit into two virtual pots — both are held in the same remainingBudget, but they have separate purposes:

The reserve is the floor the contract enforces:

require(msg.value >= minPerAgentDeposit * subcommitteeSize, InsufficientDeposit(...));

If you deposit exactly the minimum, perAgentBudget = 0 — and since agents watching RequestCreated see that cap up front, rational runners will skip the request entirely. The contract won't reject your call, but the request will almost certainly sit idle and time out. Deposit more than the floor if you want agents to actually do the work.

The per-agent share of the reward pot is computed once at request creation, stored on the Request, and emitted in RequestCreated:

perAgentBudget = (msg.value − minPerAgentDeposit × subcommitteeSize) / subcommitteeSize

perAgentBudget is the cap on what any single runner can claim — a runner's self-reported executionCost is clamped to perAgentBudget at submission.

Current per-agent prices

Runners today use fixed per-type prices in their software (no on-chain price discovery yet — that will change). If your perAgentBudget is below the price for the agent type you're invoking, runners will see the RequestCreated event, decide it's not worth their compute, and skip the request — it will sit idle and time out.

Note. On mainnet, runners operated by third parties may still report the previous JSON API Request price (0.03 SOMI) until they upgrade. A runner skips any request whose perAgentBudget is below its own price, and the payout is the median reported cost, so budgeting 0.03 SOMI per validator for JSON API Request is the safe upper bound until then. Anything not paid out is rebated.

To get your request actually executed, the deposit you send must cover the operations reserve plus the per-agent price multiplied by the subcommittee size:

msg.value ≥ minPerAgentDeposit × subSize          ← operations reserve (the contract floor)
          + per_agent_price     × subSize          ← what runners actually charge today

For the default subcommitteeSize = 3 and minPerAgentDeposit = 0.01 SOMI:

Sending more than the practical amount is fine — anything that isn't claimed (because runners reported a smaller executionCost, or because some weren't elected, etc.) is rebated to you.

Future. Per-type fixed pricing is a stop-gap. Runners will eventually price each request based on observed resource consumption (container-seconds, tokens in/out, egress, etc.), and the on-chain median will reflect actual cost rather than a hard-coded constant.

Flow of funds

The requester's msg.value goes into the AgentRequester escrow (remainingBudget = msg.value), which splits it into two pots at creation:

• Operations reserve = minPerAgentDeposit × subSize
• Agent reward pot = msg.value − reserve (perAgentBudget × subSize)

Each pot pays out as follows:

Lifecycle walkthrough

1. Request creation

uint256 deposit = somniaAgents.getRequestDeposit();      // operations reserve floor
uint256 reward  = 0.05 ether;                            // what you want each agent paid (≤)
somniaAgents.createRequest{value: deposit + reward * 3}( // 3 = default subcommittee size
    agentId,
    address(this),
    this.handleResponse.selector,
    payload
);

The contract computes perAgentBudget = reward (in this example) and emits RequestCreated(requestId, agentId, perAgentBudget, payload, subcommittee). Off-chain runners watching the event know exactly what their per-agent cap will be.

2. Runner responses

Each elected subcommittee member runs the agent off-chain, then calls:

somniaAgents.submitResponse(requestId, result, receipt, success, executionCost);

The runner's reported executionCost is capped at perAgentBudget and stored on the Response. The contract meters the gas this submission consumed and refunds it to the runner from the operations reserve.

3. Consensus and subcommittee payment

When consensus is reached (Success) or proven impossible (Failed), the contract:

1. Calls your callback (handleResponse).
2. Computes perMember = median(reported executionCosts).
3. Calls committee.deposit{value: perMember × subcommitteeSize}(elected, [perMember, ..., perMember]) — every elected member gets the same amount, regardless of whether they responded in time.

Slow geographically-distributed runners that didn't beat consensus to the punch are paid the same as the responders. This intentionally removes any incentive to rush a low-quality response.

If the committee call reverts (e.g. a misbehaving validator-bonuses contract), the budget is restored and CommitteeDepositFailed is emitted — finalisation can't be DoS'd.

If accumulated per-submission gas refunds have eaten into the operations reserve enough that perMember × subcommitteeSize > remainingBudget, the contract clamps perMember down to remainingBudget / subcommitteeSize rather than reverting. With a sensibly-tuned minPerAgentDeposit this is rare, but it does mean a request with abnormally expensive submissions can pay runners less than the reported median.

4. Rebate

Whatever's left in remainingBudget (typically the unused portion of the operations reserve) is sent back to the requester:

function _refundRemaining(Request storage req) internal {
    uint256 rebate = req.remainingBudget;
    req.remainingBudget = 0;
    (bool success, ) = req.requester.call{value: rebate}("");
}

5. Timeout path

If the request expires before consensus, anyone can call upkeepRequests():

• The keeper is reimbursed from the operations reserve (intrinsic gas amortised across the batch).
• No committee payment is made — there are no responses to derive a median from.
• The agent reward pot is refunded to the requester along with any unused operations reserve.

Reading the costs

After finalisation, getRequest(requestId) returns the full Request struct. The relevant fields:

Two events let off-chain consumers reconstruct the full distribution:

event SubcommitteePaid(uint256 indexed requestId, uint256 totalPaid, uint256 perMember);
event NativeTransferFailed(address indexed recipient, uint256 amount);

What to send for msg.value

There are three sensible patterns:

1. Floor only — not useful in practice. The contract will accept this, but perAgentBudget = 0 and agents will skip the request; it will time out without a response.

uint256 deposit = somniaAgents.getRequestDeposit();
somniaAgents.createRequest{value: deposit}(agentId, ..., payload);

Listed for completeness. Don't use it except to smoke-test that the request-creation call itself works.

2. Floor + per-agent price (the normal case). Use the per-type price from the Current per-agent prices table; runners will only pick up the request if perAgentBudget meets it.

uint256 floor = somniaAgents.getRequestDeposit();
uint256 perAgent = 0.07 ether;           // LLM Inference; pick from the table
uint256 deposit  = floor + perAgent * 3; // 3 = default subcommittee size
somniaAgents.createRequest{value: deposit}(agentId, ..., payload);

Sending more than the listed price is fine — agents are paid min(reportedExecutionCost, perAgentBudget), so any margin is rebated.

3. Custom subcommittee size:

uint256 floor = somniaAgents.getAdvancedRequestDeposit(5); // for subSize = 5
uint256 perAgent = 0.07 ether;
uint256 deposit  = floor + perAgent * 5;
somniaAgents.createAdvancedRequest{value: deposit}(
    agentId, ..., payload, 5, 3, ConsensusType.Threshold, 1 minutes
);

Receiving rebates

Make sure your contract can receive native tokens — rebates are pushed automatically on finalisation:

contract MyContract {
    receive() external payable {}
}

If the rebate transfer fails (e.g. recipient out of gas), the contract emits NativeTransferFailed(recipient, amount) and the funds remain in the AgentRequester. They can be recovered via off-chain coordination with the operator.

Configuration reference

Best practices

1. Use the deposit helpers as a floor, not the total. getRequestDeposit() returns the operations-reserve floor only. Add a per-agent reward on top.
2. Implement receive(). Without it, rebate transfers will fail (silent — emitted as NativeTransferFailed) and your funds will be stuck.
3. Watch RequestCreated.perAgentBudget. That's the value runners see and the cap they'll be paid up to.
4. Don't rely on a specific median policy. A single dishonest reporter can't manipulate the median, but with only 2 successful responders, the upper-median lands on the higher of the two values.

Next steps

• Quickstart: start invoking agents.
• Invoking from Solidity: contract integration guide.
• Custom consensus: Threshold mode for non-deterministic agents.