Execute against a pool quote

For approved 0Pools partners, execute a previously locked quote with server-side idempotency and partner-scoped state.

Execution is the state-changing step in a 0Pools flow. Your backend should execute only a quote it already locked, stored, and confirmed is still valid for the same partner and pool.

One quote, one execution path

Treat every quote as single-use. Reusing a quote, changing the request body under the same retry key, or executing after expiry should become a controlled failure state in your app.

Execution flow

Implementation shape

Read the stored quote from your database.
Verify the quote belongs to your partner, pool, and request context.
Send the execution request from your server.
Use the same Idempotency-Key for retries of the same logical execution.
Store the returned trade id with the quote id before updating user-visible state.

async function executePoolQuote(input: { quoteId: string; accountId: string }) {
  const quote = await poolQuotes.getForAccount(input.quoteId, input.accountId);

  if (!quote || quote.status !== 'active') {
    return { view: 'quote_unavailable' };
  }

  const trade = await poolsClient.executeQuote({
    poolId: quote.poolId,
    quoteId: quote.id,
    idempotencyKey: `pool-execution:${quote.id}`,
  });

  await poolTrades.upsertFromExecution({
    quoteId: quote.id,
    tradeId: trade.id,
    status: trade.status,
  });

  return { view: 'trade_processing', tradeId: trade.id };
}

Retry contract

Retry case	Expected partner behavior
Network timeout after execution request	Retry with the same idempotency key and quote id.
Duplicate button click	Suppress in the browser and let the backend return the stored execution.
Reused key with changed request	Treat as a conflict and start a new quote flow if needed.
Expired quote	Do not retry execution. Request a fresh quote.

Guardrails

Do not execute from browser code.
Do not expose internal reserve, route, or settlement mechanics in execution screens.
Do not use a different idempotency key for the same logical execution retry.
Do not mark the user outcome terminal until trade tracking or signed events close your state.