x402 inspect: fallback to on-chain gateway balance when API balance is stale

[ahmadghoniem]

Summary

• add on-chain fallback in _choose_x402_route when API gateway balance is insufficient
• keep existing API-first behavior; only use on-chain �vailableBalance when API balance appears stale
• surface explicit reason when fallback path is used

Why

In real runs, Gateway API /v1/balances can lag after deposit while on-chain �vailableBalance is already funded. This causes false �uyer_ready=false in /api/v1/x402/inspect.

Changes

• src/omniclaw/agent/routes.py

  • when get_gateway_balance is below required amount, call get_gateway_onchain_balance
  • if on-chain is sufficient, set:
    • gateway_ready=true
    • gateway_available_balance from on-chain value
    • reason: Gateway on-chain balance is sufficient (API balance appears stale)

• ests/test_x402_sdk_adapter.py

• update existing route-selection tests to mock get_gateway_onchain_balance

• add est_choose_x402_route_uses_onchain_fallback_when_api_balance_is_stale

Verification

• uv run pytest tests/test_x402_sdk_adapter.py -q
• result: 9 passed