> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Roadmap

> What's coming to OneShot

OneShot is the payment infrastructure for agent commerce. This roadmap outlines what we're building to make it the standard nobody replaces.

## Progress

<Steps>
  <Step title="Phase 1: The Wire" icon="check" iconType="solid">
    Core x402 payment flow. Agent pays service. Service delivers. Receipt generated.

    <CardGroup cols={2}>
      <Card title="Core SDK" icon="cube">
        Wallet management, x402 client, basic receipts
      </Card>

      <Card title="Wallet Providers" icon="wallet">
        Coinbase CDP Server Wallets, raw private key, custom providers
      </Card>

      <Card title="Framework Integrations" icon="plug">
        OpenClaw skill published, MCP server with auto-detect CDP/raw key
      </Card>

      <Card title="Transaction Logging" icon="list-check">
        On-chain settlement records and local transaction history
      </Card>
    </CardGroup>
  </Step>

  <Step title="Phase 2: The Eyes" icon="circle-half-stroke">
    Observability. Developers can see what their agents are spending.

    <AccordionGroup>
      <Accordion title="RoCS: Return on Cognitive Spend">
        The metric that defines agent commerce performance.

        ```
        RoCS = Value Generated / Total Cognitive Spend
        ```

        A RoCS of 3.0 means the agent creates $3 of value for every $1 it spends. Below 1.0, it's losing money. Works the same whether you're running one agent or a hundred.

        The SDK computes RoCS automatically from transaction data. Developers add one line:

        ```typescript theme={null}
        const result = await oneshot.pay(service, amount, {
          valueTag: { type: 'revenue', amount: 4.50 }
        });
        ```
      </Accordion>

      <Accordion title="Transaction Taxonomy">
        Every transaction is auto-classified by category:

        | Category       | Examples                                |
        | -------------- | --------------------------------------- |
        | Inference      | LLM API calls, embedding generation     |
        | Data           | Research APIs, enrichment, web scraping |
        | Compute        | Server provisioning, GPU rental         |
        | Tooling        | SaaS APIs, developer tools              |
        | Commerce       | Physical purchases, domain registration |
        | Agent-to-Agent | SoulMarket jobs, peer agent services    |

        ```typescript theme={null}
        const breakdown = await oneshot.spend.breakdown({ period: '30d' });
        // { inference: 42%, data: 28%, compute: 18%, commerce: 12% }
        ```
      </Accordion>

      <Accordion title="Commerce Dashboard">
        **Developer View** -- Real-time spend rate, RoCS trend, success/failure rates, cost breakdown by category, budget utilization, searchable receipt log.

        **Fleet View** -- All agents ranked by RoCS, aggregate spend, anomaly detection, cost allocation by agent, fleet-level P\&L.

        **Ecosystem View** (public) -- Total transaction volume, active agents, average RoCS, growth metrics.
      </Accordion>

      <Accordion title="Budgets and Alerts">
        ```typescript theme={null}
        const agent = await OneShot.create({
          cdp: true,
          budgets: {
            daily: 50,
            perTransaction: 5,
            alertAt: 0.8,
            pauseAt: 1.0
          },
          alerts: {
            webhook: 'https://...',
            slack: '#agent-alerts'
          }
        });
        ```

        Agent hits 80% of daily budget, developer gets notified. At 100%, the agent pauses. No empty wallets at 3am.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Phase 3: The Proof">
    Verification. Every transaction becomes a provable event.

    <AccordionGroup>
      <Accordion title="Cryptographic Receipts">
        Every x402 transaction produces a signed receipt:

        ```json theme={null}
        {
          "tx_id": "oneshot_tx_abc123",
          "timestamp": "2026-02-15T14:30:00Z",
          "payer": "0x1234...agent_wallet",
          "payee": "0x5678...service_wallet",
          "amount": "0.50",
          "currency": "USDC",
          "service": "api.example.com/v1/research",
          "request_hash": "sha256:...",
          "response_hash": "sha256:...",
          "settlement_tx": "0xabc...onchain_tx",
          "status": "settled",
          "signature": "oneshot_sig:..."
        }
        ```

        Receipts are signed by OneShot, reference on-chain settlement, and are machine-readable.

        ```typescript theme={null}
        const summary = await oneshot.receipts.summary({ period: '7d' });
        // total_spend, total_transactions, success_rate,
        // top_services, rocs, cost_by_category
        ```
      </Accordion>

      <Accordion title="Failure Mode Handling">
        | Failure                             | SDK Response                                       |
        | ----------------------------------- | -------------------------------------------------- |
        | Payment accepted, no delivery       | Auto-dispute, receipt flagged, refund requested    |
        | Price changed between quote and pay | Reject, re-quote, log discrepancy                  |
        | Double-charge                       | Block second payment, alert developer              |
        | Service unreachable after payment   | Receipt marked incomplete, auto-retry with backoff |
        | Repeated small charges (drain)      | Pause agent, alert developer, block service        |
        | Infinite loop (A pays B pays A)     | Cycle detection, break loop, alert both parties    |
        | Settlement failure                  | Queue retry, hold service delivery                 |
      </Accordion>

      <Accordion title="Circuit Breakers">
        Built-in per-service circuit breakers:

        ```typescript theme={null}
        circuitBreaker: {
          failureThreshold: 3,
          windowMs: 60000,
          cooldownMs: 300000,
          halfOpenRetries: 1
        }
        ```

        Service fails 3 times in a minute, the SDK stops paying it. Automatically.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Phase 4: The Score">
    Public benchmarks. OneShot becomes the standard.

    <AccordionGroup>
      <Accordion title="Public Benchmark">
        | Metric                   | Ecosystem Avg | Top 10% | Your Agent |
        | ------------------------ | ------------- | ------- | ---------- |
        | RoCS                     | 2.4x          | 5.1x    | 3.8x       |
        | Transaction Success Rate | 94.2%         | 99.1%   | 97.3%      |
        | Avg Settlement Time      | 1.2s          | 0.4s    | 0.8s       |
        | Cost per Transaction     | \$0.003       | \$0.001 | \$0.002    |
      </Accordion>

      <Accordion title="Agent Autonomy Gradient">
        The SDK tracks agent maturity automatically:

        | Level | Description                        | Trigger                                   |
        | ----- | ---------------------------------- | ----------------------------------------- |
        | 0     | Agent runs on human's infra        | Wallet created                            |
        | 1     | Agent has wallet, can receive      | First incoming payment                    |
        | 2     | Agent earns revenue via x402       | 10+ paid transactions as seller           |
        | 3     | Agent covers its own costs         | 30-day rolling RoCS above 1.0             |
        | 4     | Agent purchases own infrastructure | Programmatic compute/infra purchase       |
        | 5     | Agent replicates to owned infra    | Agent deploys new instance with own funds |

        Each graduation is automatic (SDK detects the threshold), verifiable (backed by receipt data), and public (opt-in via SoulMarket).
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Phase 5: The Fleet">
    Multi-agent management. The enterprise play.

    <CardGroup cols={2}>
      <Card title="Fleet Dashboard" icon="grid-2">
        Multiple agents, one view. Cross-agent analytics and cost allocation.
      </Card>

      <Card title="Safety Report" icon="shield-halved">
        Protocol safety report with red-team results and remaining framework integrations.
      </Card>
    </CardGroup>
  </Step>
</Steps>

## Framework Integrations

| Framework         | Integration                 | Status  |
| ----------------- | --------------------------- | ------- |
| OpenClaw          | SKILL.md on ClawHub         | Live    |
| MCP Server        | `@oneshot-agent/mcp-server` | Live    |
| LangChain         | `langchain-oneshot`         | Live    |
| Virtuals GAME SDK | `game-plugin-oneshot`       | Live    |
| CrewAI            | `OneShotTools.crewai()`     | Planned |
| AutoGen           | `OneShotTools.autogen()`    | Planned |
| OpenAI Agents SDK | `OneShotTools.openai()`     | Planned |

## Priority Overview

| Feature                     | Impact                   | Phase |
| --------------------------- | ------------------------ | ----- |
| Core x402 flow              | Table stakes             | 1     |
| Wallet provider abstraction | Security & adoption      | 1     |
| OpenClaw + MCP integration  | Distribution             | 1     |
| RoCS metric                 | Targeting system         | 2     |
| Transaction taxonomy        | Observability foundation | 2     |
| Developer dashboard         | Retention and trust      | 2     |
| Budget alerts               | Safety                   | 2     |
| Cryptographic receipts      | Verification             | 3     |
| Failure mode handling       | Tail-risk safety         | 3     |
| Circuit breakers            | Automatic protection     | 3     |
| Public benchmark            | Industry standard        | 4     |
| Autonomy gradient           | Agent maturity tracking  | 4     |
| Fleet dashboard             | Enterprise retention     | 5     |
| Red-team report             | Trust and marketing      | 5     |