@oobe-protocol-labs/sap-mcp-server 0.9.15 → 0.9.20

package/skills/sap-payments-x402/SKILL.md

@@ -45,9 +45,16 @@ hosted calls still proceed through x402/pay.sh plus the user's local SAP profile
 or external signer.
 
 - Free: `tools/list`, `prompts/list`, `resources/list`, `sap_profile_current`,
-  `sap_get_network_overview`, `sol_get_balance`, `spl-token_getBalance`, and
-  `spl-token_getTokenAccounts`.
-- Read premium: `sap_list_all_agents`, indexed discovery, network stats,
+  `sap_agent_start`, `sap_agent_runtime_status`, `sap_agent_context`,
+  `sap_agent_next_action`, `sap_estimate_tool_cost`, `sap_pricing_catalog`,
+  exact SAP agent/profile reads, compact `sap_list_agents` pages with
+  `limit <= 20`, `sap_get_network_overview`, core balance checks
+  (`sol_get_balance`, `spl-token_getBalance`, `spl-token_getTokenAccounts`,
+  `spl-token_getMint`, `spl-token_getSupply`, `magicblock_balance`,
+  `sap_x402_get_balance`). Enriched holdings such as `jupiter_getHoldings`
+  are paid read-premium.
+- Read premium: `sap_discover_agents`, `sap_list_all_agents`, full/enriched or
+  large `sap_list_agents` pages, indexed discovery, network stats,
   protocol/capability indexes.
 - Builder: batch SNS/domain checks, analytics, transaction builders.
 - Value action: fixed fee plus configured basis-points fee when public USD
@@ -58,6 +65,11 @@ instructions, create a payment, retry with `PAYMENT-SIGNATURE`, and capture
 `PAYMENT-RESPONSE` after settlement. If a `payShCheckoutUrl` is present, surface
 it for browser/manual checkout flows.
 
+Before retrying `payment_required`, `hosted_local_signer_required`,
+`BlockhashNotFound`, timeout, missing `sap_payments`, or an unconfirmed
+signature, call `sap_agent_next_action`. Use its `safeToRetryNow`, `nextTool`,
+and `paymentCharged` fields as the retry guard.
+
 For fast x402 execution:
 
 1. Reuse the MCP session returned by `initialize`.
@@ -65,16 +77,26 @@ For fast x402 execution:
    change, but the tool name and arguments must match the challenge.
 3. Use `PAYMENT-SIGNATURE` first; use `X-PAYMENT` only for clients that require
    the alternate header.
-4. Cache free `tools/list`, `prompts/list`, and `resources/list` locally rather
-   than paying or re-fetching repeatedly.
+4. Cache only static MCP surface metadata such as `tools/list`, `prompts/list`,
+   and `resources/list` inside the runtime when useful. Do not cache on-chain
+   balances, SAP agent rows, pricing, SNS ownership, quotes, or settlement
+   state when the user expects fresh data.
 5. Treat `PAYMENT-RESPONSE` as the receipt bound to the tool output.
 6. If the client runtime cannot sign or attach x402 payment headers itself, use
    the local SAP MCP `sap_payments_call_paid_tool` bridge configured by the SAP
    MCP wizard instead of falling back to local stdio automatically.
 
-Do not use x402 for basic balance reads. `sol_get_balance`,
-`spl-token_getBalance`, and `spl-token_getTokenAccounts` are free hosted tools
-and should be called directly through the remote SAP MCP connection.
+Do not use x402 for core balance reads. `sol_get_balance`,
+`spl-token_getBalance`, `spl-token_getTokenAccounts`, `magicblock_balance`,
+and `sap_x402_get_balance` are free hosted tools and should be called directly
+through the remote SAP MCP connection. Use `jupiter_getHoldings` only when the
+user needs enriched paid portfolio context. Always verify USDC and SOL balances
+before attempting paid calls — an agent without USDC cannot make paid calls.
+
+Before any paid tool call, use `sap_estimate_tool_cost` with the tool name to
+get the exact tier, estimated USD cost, and recommended `maxPriceUsd`. This
+prevents silent cap aborts and avoids wasting x402 attempts on local-signer-only
+tools that never issue a 402 challenge.
 
 When available locally, call `sap_payments_call_paid_tool` with `toolName`,
 `arguments`, `maxPriceUsd`, and `confirm: true`. It initializes the hosted MCP