@oobe-protocol-labs/sap-mcp-server 0.9.22 → 0.9.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (213) hide show
  1. package/.env.example +23 -9
  2. package/CHANGELOG.md +124 -6
  3. package/README.md +8 -7
  4. package/USER_DOCS/00_START_HERE.md +9 -1
  5. package/USER_DOCS/01_HOSTED_REMOTE_MCP.md +1 -1
  6. package/USER_DOCS/03_PAYMENTS_X402_PAYSH.md +1 -1
  7. package/USER_DOCS/04_CLIENT_CONFIGS.md +3 -3
  8. package/USER_DOCS/06_DESKTOP_GUI_WIZARD.md +5 -5
  9. package/config.example.json +5 -4
  10. package/dist/config/env.d.ts +22 -0
  11. package/dist/config/env.d.ts.map +1 -1
  12. package/dist/config/env.js +26 -8
  13. package/dist/config/env.js.map +1 -1
  14. package/dist/config/mcp-client-injection.d.ts.map +1 -1
  15. package/dist/config/mcp-client-injection.js +34 -5
  16. package/dist/config/mcp-client-injection.js.map +1 -1
  17. package/dist/config/paths.d.ts +9 -1
  18. package/dist/config/paths.d.ts.map +1 -1
  19. package/dist/config/paths.js +15 -1
  20. package/dist/config/paths.js.map +1 -1
  21. package/dist/config/profiles.d.ts +5 -0
  22. package/dist/config/profiles.d.ts.map +1 -1
  23. package/dist/config/profiles.js +37 -9
  24. package/dist/config/profiles.js.map +1 -1
  25. package/dist/config/wizard.d.ts.map +1 -1
  26. package/dist/config/wizard.js +44 -1
  27. package/dist/config/wizard.js.map +1 -1
  28. package/dist/config-cli.d.ts.map +1 -1
  29. package/dist/config-cli.js +17 -1
  30. package/dist/config-cli.js.map +1 -1
  31. package/dist/core/constants.d.ts +1 -1
  32. package/dist/core/constants.js +1 -1
  33. package/dist/core/logger.js +1 -1
  34. package/dist/memory/async-processor.d.ts +107 -0
  35. package/dist/memory/async-processor.d.ts.map +1 -0
  36. package/dist/memory/async-processor.js +204 -0
  37. package/dist/memory/async-processor.js.map +1 -0
  38. package/dist/memory/auto-record.d.ts +47 -0
  39. package/dist/memory/auto-record.d.ts.map +1 -0
  40. package/dist/memory/auto-record.js +133 -0
  41. package/dist/memory/auto-record.js.map +1 -0
  42. package/dist/memory/database.d.ts +103 -0
  43. package/dist/memory/database.d.ts.map +1 -0
  44. package/dist/memory/database.js +337 -0
  45. package/dist/memory/database.js.map +1 -0
  46. package/dist/memory/hermes-bridge.d.ts +70 -0
  47. package/dist/memory/hermes-bridge.d.ts.map +1 -0
  48. package/dist/memory/hermes-bridge.js +155 -0
  49. package/dist/memory/hermes-bridge.js.map +1 -0
  50. package/dist/memory/index.d.ts +23 -0
  51. package/dist/memory/index.d.ts.map +1 -0
  52. package/dist/memory/index.js +22 -0
  53. package/dist/memory/index.js.map +1 -0
  54. package/dist/memory/memory-store.d.ts +76 -0
  55. package/dist/memory/memory-store.d.ts.map +1 -0
  56. package/dist/memory/memory-store.js +231 -0
  57. package/dist/memory/memory-store.js.map +1 -0
  58. package/dist/memory/stream-buffer-store.d.ts +69 -0
  59. package/dist/memory/stream-buffer-store.d.ts.map +1 -0
  60. package/dist/memory/stream-buffer-store.js +182 -0
  61. package/dist/memory/stream-buffer-store.js.map +1 -0
  62. package/dist/memory/tool-call-store.d.ts +68 -0
  63. package/dist/memory/tool-call-store.d.ts.map +1 -0
  64. package/dist/memory/tool-call-store.js +189 -0
  65. package/dist/memory/tool-call-store.js.map +1 -0
  66. package/dist/memory/types.d.ts +197 -0
  67. package/dist/memory/types.d.ts.map +1 -0
  68. package/dist/memory/types.js +15 -0
  69. package/dist/memory/types.js.map +1 -0
  70. package/dist/memory/utils.d.ts +30 -0
  71. package/dist/memory/utils.d.ts.map +1 -0
  72. package/dist/memory/utils.js +47 -0
  73. package/dist/memory/utils.js.map +1 -0
  74. package/dist/payments/hosted-tool-eligibility.d.ts.map +1 -1
  75. package/dist/payments/hosted-tool-eligibility.js +4 -6
  76. package/dist/payments/hosted-tool-eligibility.js.map +1 -1
  77. package/dist/payments/monetization-gate.d.ts +39 -0
  78. package/dist/payments/monetization-gate.d.ts.map +1 -1
  79. package/dist/payments/monetization-gate.js +165 -11
  80. package/dist/payments/monetization-gate.js.map +1 -1
  81. package/dist/payments/pay-sh-spec.d.ts.map +1 -1
  82. package/dist/payments/pay-sh-spec.js +4 -2
  83. package/dist/payments/pay-sh-spec.js.map +1 -1
  84. package/dist/payments/pricing.d.ts +3 -1
  85. package/dist/payments/pricing.d.ts.map +1 -1
  86. package/dist/payments/pricing.js +137 -56
  87. package/dist/payments/pricing.js.map +1 -1
  88. package/dist/payments/x402-paid-call.d.ts.map +1 -1
  89. package/dist/payments/x402-paid-call.js +26 -2
  90. package/dist/payments/x402-paid-call.js.map +1 -1
  91. package/dist/premium/builtin-plugins.d.ts +42 -0
  92. package/dist/premium/builtin-plugins.d.ts.map +1 -1
  93. package/dist/premium/builtin-plugins.js +91 -10
  94. package/dist/premium/builtin-plugins.js.map +1 -1
  95. package/dist/premium/manifest-builder.d.ts.map +1 -1
  96. package/dist/premium/manifest-builder.js +43 -7
  97. package/dist/premium/manifest-builder.js.map +1 -1
  98. package/dist/premium/meme-radar-capabilities.js +9 -9
  99. package/dist/premium/meme-radar-capabilities.js.map +1 -1
  100. package/dist/premium/plugin-validator.d.ts.map +1 -1
  101. package/dist/premium/plugin-validator.js +62 -1
  102. package/dist/premium/plugin-validator.js.map +1 -1
  103. package/dist/premium/provider-bridge.d.ts +25 -1
  104. package/dist/premium/provider-bridge.d.ts.map +1 -1
  105. package/dist/premium/provider-bridge.js +130 -20
  106. package/dist/premium/provider-bridge.js.map +1 -1
  107. package/dist/premium/session-manager.d.ts.map +1 -1
  108. package/dist/premium/session-manager.js +12 -3
  109. package/dist/premium/session-manager.js.map +1 -1
  110. package/dist/premium/tech-fundamentals-capabilities.js +5 -5
  111. package/dist/premium/tech-fundamentals-capabilities.js.map +1 -1
  112. package/dist/premium/trading-capabilities.js +5 -5
  113. package/dist/premium/trading-capabilities.js.map +1 -1
  114. package/dist/premium/webhook-engine.d.ts.map +1 -1
  115. package/dist/premium/webhook-engine.js +7 -1
  116. package/dist/premium/webhook-engine.js.map +1 -1
  117. package/dist/prompts/context/sap-agent-context.prompt.js +4 -3
  118. package/dist/prompts/context/sap-agent-context.prompt.js.map +1 -1
  119. package/dist/prompts/context/sap-agent-intent-router.prompt.js +1 -1
  120. package/dist/prompts/payments/explain-x402-settlement.prompt.js +1 -1
  121. package/dist/remote/premium-routes.d.ts.map +1 -1
  122. package/dist/remote/premium-routes.js +3 -2
  123. package/dist/remote/premium-routes.js.map +1 -1
  124. package/dist/remote/public-home/sections.d.ts.map +1 -1
  125. package/dist/remote/public-home/sections.js +2 -3
  126. package/dist/remote/public-home/sections.js.map +1 -1
  127. package/dist/remote/public-home/styles.d.ts +1 -1
  128. package/dist/remote/public-home/styles.js +2 -2
  129. package/dist/remote/server.d.ts.map +1 -1
  130. package/dist/remote/server.js +19 -4
  131. package/dist/remote/server.js.map +1 -1
  132. package/dist/server/server-metadata.js +1 -1
  133. package/dist/strategies/strategy-store.d.ts +82 -0
  134. package/dist/strategies/strategy-store.d.ts.map +1 -0
  135. package/dist/strategies/strategy-store.js +165 -0
  136. package/dist/strategies/strategy-store.js.map +1 -0
  137. package/dist/tools/agent-start-tool.d.ts.map +1 -1
  138. package/dist/tools/agent-start-tool.js +103 -16
  139. package/dist/tools/agent-start-tool.js.map +1 -1
  140. package/dist/tools/client-sdk-tools.d.ts.map +1 -1
  141. package/dist/tools/client-sdk-tools.js +156 -12
  142. package/dist/tools/client-sdk-tools.js.map +1 -1
  143. package/dist/tools/estimate-tool-cost.d.ts.map +1 -1
  144. package/dist/tools/estimate-tool-cost.js +11 -4
  145. package/dist/tools/estimate-tool-cost.js.map +1 -1
  146. package/dist/tools/index.d.ts +1 -0
  147. package/dist/tools/index.d.ts.map +1 -1
  148. package/dist/tools/index.js +2 -0
  149. package/dist/tools/index.js.map +1 -1
  150. package/dist/tools/magicblock-tools.js +8 -8
  151. package/dist/tools/magicblock-tools.js.map +1 -1
  152. package/dist/tools/memory-tools.d.ts +26 -0
  153. package/dist/tools/memory-tools.d.ts.map +1 -0
  154. package/dist/tools/memory-tools.js +533 -0
  155. package/dist/tools/memory-tools.js.map +1 -0
  156. package/dist/tools/perp-tools.d.ts +7 -9
  157. package/dist/tools/perp-tools.d.ts.map +1 -1
  158. package/dist/tools/perp-tools.js +404 -367
  159. package/dist/tools/perp-tools.js.map +1 -1
  160. package/dist/tools/premium-tools.d.ts.map +1 -1
  161. package/dist/tools/premium-tools.js +8 -2
  162. package/dist/tools/premium-tools.js.map +1 -1
  163. package/dist/tools/profile-tools.d.ts.map +1 -1
  164. package/dist/tools/profile-tools.js +18 -1
  165. package/dist/tools/profile-tools.js.map +1 -1
  166. package/dist/tools/quick-context-tool.d.ts.map +1 -1
  167. package/dist/tools/quick-context-tool.js +101 -9
  168. package/dist/tools/quick-context-tool.js.map +1 -1
  169. package/dist/tools/register-tools.d.ts.map +1 -1
  170. package/dist/tools/register-tools.js +3 -0
  171. package/dist/tools/register-tools.js.map +1 -1
  172. package/dist/tools/sap-sdk-tools.d.ts.map +1 -1
  173. package/dist/tools/sap-sdk-tools.js +14 -13
  174. package/dist/tools/sap-sdk-tools.js.map +1 -1
  175. package/dist/tools/session-context-packet.d.ts +19 -0
  176. package/dist/tools/session-context-packet.d.ts.map +1 -0
  177. package/dist/tools/session-context-packet.js +256 -0
  178. package/dist/tools/session-context-packet.js.map +1 -0
  179. package/dist/tools/skills-tools.d.ts +10 -0
  180. package/dist/tools/skills-tools.d.ts.map +1 -1
  181. package/dist/tools/skills-tools.js +19 -0
  182. package/dist/tools/skills-tools.js.map +1 -1
  183. package/dist/tools/transaction-tools.d.ts +1 -0
  184. package/dist/tools/transaction-tools.d.ts.map +1 -1
  185. package/dist/tools/transaction-tools.js +248 -9
  186. package/dist/tools/transaction-tools.js.map +1 -1
  187. package/dist/tools/x402-paid-call-tool.d.ts.map +1 -1
  188. package/dist/tools/x402-paid-call-tool.js +55 -21
  189. package/dist/tools/x402-paid-call-tool.js.map +1 -1
  190. package/dist/wizard-core/desktop-flow.d.ts.map +1 -1
  191. package/dist/wizard-core/desktop-flow.js +4 -2
  192. package/dist/wizard-core/desktop-flow.js.map +1 -1
  193. package/docs/06_PAYMENTS_X402_AND_PAYSH.md +38 -13
  194. package/docs/07_ENDPOINTS_AND_CLIENTS.md +1 -1
  195. package/docs/09_TOOLS_SKILLS_AND_AGENT_GUIDE.md +14 -6
  196. package/docs/13_BOUNTY_PROGRAM_PROPOSAL.md +1 -1
  197. package/docs/14_DESKTOP_WIZARD_RELEASE.md +3 -3
  198. package/docs/15_DASHBOARD_SCREENSHARE_SCRIPT.md +1 -1
  199. package/docs/BRANCH_AND_CI.md +2 -2
  200. package/docs/README.md +1 -1
  201. package/package.json +3 -1
  202. package/server.json +3 -3
  203. package/skills/README.md +3 -3
  204. package/skills/sap-agent-registry/SKILL.md +2 -2
  205. package/skills/sap-agentkit/SKILL.md +10 -4
  206. package/skills/sap-defi/SKILL.md +42 -5
  207. package/skills/sap-discovery-indexing/SKILL.md +4 -3
  208. package/skills/sap-market-data/SKILL.md +9 -5
  209. package/skills/sap-mcp/SKILL.md +37 -24
  210. package/skills/sap-mcp/TOOL_REFERENCE.md +9 -8
  211. package/skills/sap-operations/SKILL.md +5 -4
  212. package/skills/sap-payments-x402/SKILL.md +34 -19
  213. package/assets/logos/drift.svg +0 -12
@@ -1,8 +1,8 @@
1
1
  # SAP DeFi
2
2
 
3
- Use this skill for Jupiter swaps, DCA, limit orders, Drift, Adrena, Lulo,
4
- Raydium, Orca, Meteora, OpenBook, Manifest, Pump.fun, Jito, bridges, and
5
- staking protocols.
3
+ Use this skill for Jupiter swaps, DCA, limit orders, perps planning, chart
4
+ analysis, Lulo, Raydium, Orca, Meteora, OpenBook, Manifest, Pump.fun, Jito,
5
+ bridges, and staking protocols.
6
6
 
7
7
  ## Jupiter
8
8
 
@@ -24,8 +24,14 @@ staking protocols.
24
24
 
25
25
  ## Protocol Tools
26
26
 
27
- - `drift_*`
28
- - `adrena_*`
27
+ - `sap_perp_trade_plan`
28
+ - `sap_perp_markets`
29
+ - `sap_perp_position_info`
30
+ - `sap_perp_funding_history`
31
+ - `sap_perp_liquidation_zones`
32
+ - `sap_chart_ohlc`
33
+ - `sap_chart_long_term`
34
+ - `sap_chart_volume_profile`
29
35
  - `lulo_*`
30
36
  - `raydium-pools_*`
31
37
  - `orca_*`
@@ -52,6 +58,37 @@ staking protocols.
52
58
  use `sap_preview_transaction`, `sap_sign_transaction`, and
53
59
  `sap_submit_signed_transaction`. Do not write ad-hoc signing scripts.
54
60
 
61
+ ## Professional Perps Flow
62
+
63
+ For perps or leveraged trading tasks, start with hosted SAP analytics and
64
+ planning tools before any value-moving action:
65
+
66
+ 1. Call `sap_perp_markets` to inspect supported markets, mark prices, funding,
67
+ and open interest.
68
+ 2. Call `sap_perp_position_info` when the user has an existing wallet position.
69
+ 3. Call `sap_chart_ohlc`, `sap_chart_long_term`, or
70
+ `sap_chart_volume_profile` for trend, timeframe, and liquidity context.
71
+ 4. Call `sap_perp_liquidation_zones` to understand liquidation distance and
72
+ crowded-risk areas.
73
+ 5. Call `sap_perp_trade_plan` with market, side, collateral amount, leverage,
74
+ entry price, stop loss, take profit, max slippage, and max account-risk
75
+ policy.
76
+
77
+ `sap_perp_trade_plan` is analysis-only. It returns trader-grade risk flags,
78
+ liquidation estimate, reward/risk, and an execution checklist. `sap_perp_markets`
79
+ may return `dataAvailability.status="unavailable"` when the configured RPC does
80
+ not serve the required perps account indexes; treat that as missing data, not as
81
+ proof that markets do not exist. Do not create temporary signing scripts, do not
82
+ guess perps account graphs, and do not execute a perps transaction unless SAP MCP
83
+ exposes a typed unsigned builder or a local SAP payments/signing tool for that
84
+ exact action.
85
+
86
+ Direct Adrena signer tools may exist in some local AgentKit builds, but hosted
87
+ SAP MCP blocks them before x402 payment because the hosted server is
88
+ accountless. Do not route `adrena_openPosition`, `adrena_closePosition`, or
89
+ collateral-changing Adrena calls through `sap_payments_call_paid_tool`; there is
90
+ no payment challenge and no unsigned transaction to finalize.
91
+
55
92
  ## Safety
56
93
 
57
94
  DeFi execution can lose funds through slippage, MEV, wrong decimals, or bad
@@ -18,7 +18,7 @@ indexes, and filtered agent discovery.
18
18
 
19
19
  ## Rules
20
20
 
21
- - Start with free orientation when possible:
21
+ - Start with low-cost micro-read orientation when possible:
22
22
  - `sap_agent_context` for a one-shot compact context read and routing hints.
23
23
  - `sap_get_agent` or `sap_get_agent_profile` for a known owner wallet.
24
24
  - `sap_is_agent_active` for a known owner wallet status check.
@@ -31,8 +31,9 @@ indexes, and filtered agent discovery.
31
31
  - Use `sap_list_all_agents` for global directory requests or when the user asks
32
32
  for the whole SAP ecosystem. Keep the first page small and follow
33
33
  `pagination.nextCursor` only when the previous page is useful.
34
- - Use paid discovery only when the user needs search, enrichment, full rows,
35
- large pages, analytics, or global enumeration beyond the free compact page.
34
+ - Use read-premium discovery only when the user needs search, enrichment, full
35
+ rows, large pages, analytics, or global enumeration beyond the compact
36
+ micro-read page.
36
37
  - Prefer exact filters before broad scans: `wallet` when a wallet is known,
37
38
  `query` for an agent name such as `XONA`, and `capability` for one exact
38
39
  capability such as `creative:imageGeneration`.
@@ -24,11 +24,15 @@ trending assets, token metadata, and security/intelligence checks.
24
24
 
25
25
  ## Flow
26
26
 
27
- 1. Resolve token mints with `jupiter_searchTokens` when the user gives only a
28
- ticker.
29
- 2. Use Pyth for oracle-style price feeds.
30
- 3. Use CoinGecko for market data, OHLCV, pools, trending, gainers, and losers.
31
- 4. Use `jupiter_shield` and `jupiter_getTokenInfo` for token risk context.
27
+ 1. If the mint/feed id is already known, start with free single-asset snapshots:
28
+ `jupiter_getPrice`, `pyth_getPrice`, or `coingecko_getTokenPrice`.
29
+ 2. Resolve token mints with `jupiter_searchTokens` only when the user gives
30
+ a ticker or ambiguous asset name; this is broader discovery and may be paid.
31
+ 3. Use `jupiter_getQuote` for executable route pricing, not as a generic price
32
+ check. Quotes are fresh, paid, and must not be cached as truth.
33
+ 4. Use Pyth history, CoinGecko OHLCV/pools/trending/gainers/losers, and Jupiter
34
+ token lists only when the user needs broader market context.
35
+ 5. Use `jupiter_shield` and `jupiter_getTokenInfo` for token risk context.
32
36
 
33
37
  ## Safety
34
38
 
@@ -9,6 +9,7 @@ safe signing behavior.
9
9
  If the user says "Start SAP MCP", "Initialize SAP MCP", "Load SAP", or "SAP
10
10
  mode", treat it as the activation command. Call `sap_agent_start` when it is
11
11
  available, then call `sap_agent_runtime_status` with the closest intent and
12
+ `sap_prepare_action` when the request is more than a status check. Then call
12
13
  `sap_skills_bundle` with `includeContents: true`. Load the returned SAP MCP
13
14
  skill contents into context before selecting advanced tools.
14
15
 
@@ -22,18 +23,19 @@ Always inspect runtime context through MCP tools, not by reading config files:
22
23
 
23
24
  1. `sap_agent_start`
24
25
  2. `sap_agent_runtime_status` with `intent: "connection"`, `"paid-call"`, `"registry-write"`, `"transaction-finalize"`, `"escrow"`, `"identity"`, or `"general"`
25
- 3. `sap_agent_context` for free compact agent/directory orientation before paid discovery
26
- 4. `sap_skills_bundle` with `includeContents: true`
27
- 5. `sap_pricing_catalog` before estimating hosted paid call tiers
28
- 6. `sap_agent_next_action` before retrying after any SAP MCP error or partial write result
29
- 7. `sap_skills_upgrade_plan` when local skills are missing or stale
30
- 8. `sap_runtime_repair_plan` when hosted tools are connected but `sap_payments` is missing
31
- 9. `sap_protocol_invariants` before SAP registry writes or when treasury, protocol fee, hosted write routing, or local signer routing is unclear
32
- 10. `sap_agent_identity_plan` before agent registration, profile-image updates, Metaplex identity, SNS linking, or full identity setup
33
- 11. `sap_profile_current`
34
- 12. `sap_profile_list`
35
- 13. `sap_profile_public_key`
36
- 14. `sap_network_stats`
26
+ 3. `sap_prepare_action` with the closest intent before paid calls, swaps, registry writes, identity updates, Escrow V2, external x402 agents, premium streams, or transaction finalization
27
+ 4. `sap_agent_context` for compact micro-read agent/directory orientation before broad discovery
28
+ 5. `sap_skills_bundle` with `includeContents: true`
29
+ 6. `sap_pricing_catalog` before estimating hosted paid call tiers
30
+ 7. `sap_agent_next_action` before retrying after any SAP MCP error or partial write result
31
+ 8. `sap_skills_upgrade_plan` when local skills are missing or stale
32
+ 9. `sap_runtime_repair_plan` when hosted tools are connected but `sap_payments` is missing
33
+ 10. `sap_protocol_invariants` before SAP registry writes or when treasury, protocol fee, hosted write routing, or local signer routing is unclear
34
+ 11. `sap_agent_identity_plan` before agent registration, profile-image updates, Metaplex identity, SNS linking, or full identity setup
35
+ 12. `sap_profile_current`
36
+ 13. `sap_profile_list`
37
+ 14. `sap_profile_public_key`
38
+ 15. `sap_network_stats`
37
39
 
38
40
  For simple "are you connected?" checks, do not dump tool counts or inspect
39
41
  local files. Use `sap_agent_runtime_status` first and answer with the hosted
@@ -57,8 +59,14 @@ and error strings unchanged.
57
59
  agent profile reads as fresh data. Do not rely on old chat memory when the
58
60
  user asks for current state; use exact lightweight reads first, then paid
59
61
  discovery only when enrichment or broad search is needed.
60
- - Use free exact/base reads first when the wallet, PDA, or a small orientation
61
- page is enough: `sap_agent_context`, `sap_get_agent`, `sap_get_agent_profile`,
62
+ - Treat session memory as operational context and proof tape, not cached market
63
+ or on-chain truth. It may store active profile names, public wallet keys,
64
+ runtime namespace availability, receipts, signatures, and error
65
+ classifications. It must not be used as truth for token prices, Jupiter
66
+ quotes/orders, balances, blockhashes, simulations, liquidity, routes, or SAP
67
+ account state.
68
+ - Use low-cost exact/base micro-reads first when the wallet, PDA, or a small
69
+ orientation page is enough: `sap_agent_context`, `sap_get_agent`, `sap_get_agent_profile`,
62
70
  `sap_get_agent_stats`, `sap_is_agent_active`, `sap_get_global_state`, and
63
71
  `sap_list_agents` with `limit <= 20`, `view: "compact"`, and
64
72
  `includeProtocolIndexes: false`.
@@ -69,9 +77,9 @@ and error strings unchanged.
69
77
  - Use `sap_list_all_agents` when the user asks for all current SAP ecosystem
70
78
  agents. It performs global on-chain `AgentAccount` enumeration and returns
71
79
  `pagination.nextCursor` when more pages are available.
72
- - Use `sap_list_agents` for a free compact orientation page first. Larger
80
+ - Use `sap_list_agents` for a compact micro-read orientation page first. Larger
73
81
  pages, `view: "full"`, hydration, protocol index summaries, and global scans
74
- are paid read-premium.
82
+ are read-premium.
75
83
  - Use `sap_fetch_protocol_index` when a specific protocol ID is known.
76
84
  - If a capability lookup returns zero results, retry with `query` or `wallet`
77
85
  before saying an agent is absent. AgentAccount rows are canonical; indexes can
@@ -100,7 +108,7 @@ Use the bundled routing map for local MCP tool selection:
100
108
 
101
109
  SAP MCP startup and skill bootstrap tools are free context/setup tools. Call
102
110
  `sap_agent_start`, `sap_agent_runtime_status`, `sap_agent_context`,
103
- `sap_agent_next_action`, `sap_pricing_catalog`,
111
+ `sap_prepare_action`, `sap_agent_next_action`, `sap_pricing_catalog`,
104
112
  `sap_skills_list`, `sap_skills_bundle`, `sap_skills_upgrade_plan`,
105
113
  `sap_runtime_repair_plan`, and local `sap_skills_install` directly. Do not
106
114
  route startup, runtime status, pricing catalog, skill listing, bundling,
@@ -184,13 +192,15 @@ the local `sap_payments.sap_payments_readiness` bridge when it is configured.
184
192
  Use `sap_payments.sap_payments_profile_current` only as a narrower compatibility
185
193
  profile check.
186
194
 
187
- Basic wallet reads are free on hosted SAP MCP. Call `sol_get_balance`,
188
- `spl-token_getBalance`, `spl-token_getTokenAccounts`, and `magicblock_balance`
189
- directly on the hosted server. Do not send these balance checks through
190
- `sap_payments_call_paid_tool`, and do not summarize a balance read as a
191
- facilitator `BlockhashNotFound` problem unless a paid tool actually returned
192
- that error. Use `jupiter_getHoldings` only when the user needs enriched paid
193
- portfolio context.
195
+ Basic wallet and price-readiness checks are free hosted reads. Call
196
+ `sol_get_balance`, `spl-token_getBalance`, `spl-token_getTokenAccounts`,
197
+ `sap_x402_get_balance`, `magicblock_balance`, `jupiter_getPrice`,
198
+ `pyth_getPrice`, and `coingecko_getTokenPrice` directly on the hosted server
199
+ when the user needs fresh readiness data. Do not send these checks through
200
+ `sap_payments_call_paid_tool`, and do not summarize a readiness read as a
201
+ facilitator `BlockhashNotFound` problem unless a paid x402 tool actually
202
+ returned that error. Use `jupiter_getHoldings` only when the user needs enriched
203
+ read-premium portfolio context.
194
204
 
195
205
  Before any paid tool call, use `sap_estimate_tool_cost` with the tool name to
196
206
  get the exact pricing tier, estimated USD cost, and recommended `maxPriceUsd`.
@@ -198,6 +208,9 @@ This prevents silent cap aborts and failed x402 attempts on local-signer-only
198
208
  tools. For local-signer-only tools (e.g. `sap_register_agent`), the estimate
199
209
  will say `tier: "local-signer-only"` and tell you to use the local
200
210
  `sap_payments_*` equivalent instead of `sap_payments_call_paid_tool`.
211
+ For any intent-level workflow, call `sap_prepare_action` before execution. It
212
+ returns the correct hosted/local route, fresh-data requirements, confirmation
213
+ policy, retry rules, and proof-tape shape without charging x402.
201
214
 
202
215
  If a hosted paid tool returns `BlockhashNotFound`,
203
216
  `transaction_simulation_failed`, `smart_wallet_simulation_failed`, `node is
@@ -49,7 +49,7 @@ SAP registry and discovery:
49
49
  `sap_deactivate_tool`, `sap_reactivate_tool`,
50
50
  `sap_report_tool_invocations`, `sap_report_calls`.
51
51
 
52
- Use free exact/base reads before paid discovery when possible:
52
+ Use low-cost exact/base micro-reads before broad discovery when possible:
53
53
  `sap_agent_context`, `sap_get_agent`, `sap_get_agent_profile`,
54
54
  `sap_get_agent_stats`, `sap_is_agent_active`, `sap_get_global_state`, and
55
55
  `sap_list_agents` with `limit <= 20`, `view: "compact"`, and
@@ -174,13 +174,9 @@ Jupiter protocol toolkit:
174
174
  `jupiter_getLimitOrders`, `jupiter_createDCA`, `jupiter_executeDCA`,
175
175
  `jupiter_cancelDCA`, `jupiter_getDCAOrders`, `jupiter_smartSwap`.
176
176
 
177
- `adrena_addCollateral`, `adrena_closePosition`, `adrena_getPositions`,
178
- `adrena_openPosition`, `adrena_removeCollateral`,
179
177
  `bridging_bridgeDeBridge`, `bridging_bridgeDeBridgeStatus`,
180
178
  `bridging_bridgeWormhole`, `bridging_bridgeWormholeStatus`,
181
- `drift_borrow`, `drift_closePerpPosition`, `drift_deposit`,
182
- `drift_getPositions`, `drift_lend`, `drift_openPerpPosition`,
183
- `drift_withdraw`, `jito_getBundleStatus`, `jito_getTipEstimate`,
179
+ `jito_getBundleStatus`, `jito_getTipEstimate`,
184
180
  `jito_sendBundle`, `lulo_deposit`, `lulo_getBestRates`,
185
181
  `lulo_getPositions`, `lulo_withdraw`, `manifest_cancelOrder`,
186
182
  `manifest_createMarket`, `manifest_getOrderbook`,
@@ -201,7 +197,7 @@ Protocol routing shortcuts:
201
197
 
202
198
  | User intent | Most specific tools |
203
199
  | --- | --- |
204
- | SOL or SPL balance (free) | `sol_get_balance`, `spl-token_getBalance`, `spl-token_getTokenAccounts`, `magicblock_balance` |
200
+ | SOL or SPL balance (micro-read) | `sol_get_balance`, `spl-token_getBalance`, `spl-token_getTokenAccounts`, `magicblock_balance` |
205
201
  | Enriched holdings (paid read-premium) | `jupiter_getHoldings` |
206
202
  | Pre-call cost estimate (free) | `sap_estimate_tool_cost` |
207
203
  | Pricing catalog (free) | `sap_pricing_catalog` |
@@ -209,7 +205,7 @@ Protocol routing shortcuts:
209
205
  | Token launch/mint/burn | `spl-token_deployToken`, `spl-token_mintTo`, `spl-token_burn` |
210
206
  | Jupiter quote/swap | `jupiter_getQuote`, `jupiter_smartSwap`, `jupiter_swap`, `jupiter_swapInstructions` |
211
207
  | Jupiter limit/DCA | `jupiter_createLimitOrder`, `jupiter_getLimitOrders`, `jupiter_createDCA`, `jupiter_getDCAOrders` |
212
- | Perps/lending | `drift_*`, `adrena_*`, `lulo_*` |
208
+ | Perps/lending | `sap_perp_trade_plan`, `sap_perp_*`, `sap_chart_*`, `lulo_*` |
213
209
  | Liquidity pools | `raydium-pools_*`, `orca_*`, `meteora_*` |
214
210
  | Orderbooks | `openbook_*`, `manifest_*` |
215
211
  | Price data | `pyth_*`, `coingecko_*` |
@@ -223,3 +219,8 @@ Social, Blinks, bounties, gaming:
223
219
  `blinks_getAction`, `blinks_resolveBlinkUrl`, `blinks_validateActionsJson`,
224
220
  `gibwork_createBounty`, `gibwork_listBounties`, `gibwork_submitWork`,
225
221
  `send-arcade_listGames`, `send-arcade_playGame`.
222
+
223
+ Perps note: SAP MCP hosted supports perps analytics and trader-grade planning,
224
+ not direct hosted Adrena execution. If direct Adrena signer tools are visible in
225
+ a local runtime, use them only with that local runtime's signer path and policy.
226
+ Do not route direct Adrena writes through hosted x402 paid-call replay.
@@ -36,12 +36,13 @@ Use `sap_discover_agents` for targeted hosted directory reads by `query`,
36
36
  `wallet`, `agentPda`, `protocol`, `capability`, `capabilities`, or
37
37
  `hasX402Endpoint`. Use `sap_list_all_agents` for global current ecosystem
38
38
  requests, keep pages small, and continue with `pagination.nextCursor`.
39
- For first-pass orientation, prefer free reads: `sap_agent_context`,
39
+ For first-pass orientation, prefer free control-plane tools, then low-cost
40
+ micro-read exact/base reads: `sap_agent_context`,
40
41
  `sap_get_agent`, `sap_get_agent_profile`, `sap_get_agent_stats`,
41
42
  `sap_is_agent_active`, `sap_get_global_state`, and `sap_list_agents` with `limit <= 20`,
42
- `view: "compact"`, and `includeProtocolIndexes: false`. Use paid discovery
43
- only when the user needs search, enrichment, full rows, large pages, analytics,
44
- or global enumeration beyond the compact page.
43
+ `view: "compact"`, and `includeProtocolIndexes: false`. Use read-premium
44
+ discovery only when the user needs search, enrichment, full rows, large pages,
45
+ analytics, or global enumeration beyond the compact page.
45
46
 
46
47
  Before registering or updating an agent profile, call free
47
48
  `sap_protocol_invariants` when treasury, registration fee, hosted write route,
@@ -16,6 +16,7 @@ workflows, and hosted SAP MCP x402/pay.sh monetization.
16
16
  - `sap_payments_prepare_challenge`
17
17
  - `sap_payments_sign_challenge`
18
18
  - `sap_payments_verify_receipt`
19
+ - `sap_prepare_action`
19
20
  - `sap_x402_paid_call`
20
21
  - `sap_create_subscription`
21
22
  - `sap_fund_subscription`
@@ -44,18 +45,19 @@ the non-custodial model: OOBE does not hold user keys. Paid and value-moving
44
45
  hosted calls still proceed through x402/pay.sh plus the user's local SAP profile
45
46
  or external signer.
46
47
 
47
- - Free: `tools/list`, `prompts/list`, `resources/list`, `sap_profile_current`,
48
- `sap_agent_start`, `sap_agent_runtime_status`, `sap_agent_context`,
48
+ - Free: MCP handshake, `tools/list`, `prompts/list`, `resources/list`,
49
+ `sap_profile_current`, `sap_agent_start`, `sap_agent_runtime_status`,
49
50
  `sap_agent_next_action`, `sap_estimate_tool_cost`, `sap_pricing_catalog`,
50
- exact SAP agent/profile reads, compact `sap_list_agents` pages with
51
- `limit <= 20`, `sap_get_network_overview`, core balance checks
52
- (`sol_get_balance`, `spl-token_getBalance`, `spl-token_getTokenAccounts`,
53
- `spl-token_getMint`, `spl-token_getSupply`, `magicblock_balance`,
54
- `sap_x402_get_balance`). Enriched holdings such as `jupiter_getHoldings`
55
- are paid read-premium.
51
+ repair/status tools, local payment bridge control, transaction
52
+ preview/finalization helpers, SOL/SPL/x402 balance readiness, single-asset
53
+ price snapshots, and memory/audit helpers.
54
+ - Micro read: exact SAP agent/profile reads, compact `sap_list_agents` pages
55
+ with `limit <= 20`, `sap_get_network_overview`, SNS availability, escrow
56
+ state, and lightweight trader/perps context.
56
57
  - Read premium: `sap_discover_agents`, `sap_list_all_agents`, full/enriched or
57
- large `sap_list_agents` pages, indexed discovery, network stats,
58
- protocol/capability indexes.
58
+ large `sap_list_agents` pages, enriched holdings, indexed discovery, network
59
+ stats, protocol/capability indexes, DAS, token lists, quotes/routes, and
60
+ OHLCV/history.
59
61
  - Builder: batch SNS/domain checks, analytics, transaction builders.
60
62
  - Value action: fixed fee plus configured basis-points fee when public USD
61
63
  notional fields are present.
@@ -70,6 +72,15 @@ Before retrying `payment_required`, `hosted_local_signer_required`,
70
72
  signature, call `sap_agent_next_action`. Use its `safeToRetryNow`, `nextTool`,
71
73
  and `paymentCharged` fields as the retry guard.
72
74
 
75
+ Before starting a paid or value-moving workflow, call the free hosted
76
+ `sap_prepare_action` planner with the closest intent. It returns:
77
+
78
+ - fresh data that must be fetched again before payment/signing;
79
+ - whether to use hosted `sap`, local `sap_payments`, or a hosted unsigned
80
+ builder plus `sap_payments_finalize_transaction`;
81
+ - max-price and confirmation guidance;
82
+ - retry rules and the proof-tape fields to report back to the user.
83
+
73
84
  For fast x402 execution:
74
85
 
75
86
  1. Reuse the MCP session returned by `initialize`.
@@ -78,20 +89,24 @@ For fast x402 execution:
78
89
  3. Use `PAYMENT-SIGNATURE` first; use `X-PAYMENT` only for clients that require
79
90
  the alternate header.
80
91
  4. Cache only static MCP surface metadata such as `tools/list`, `prompts/list`,
81
- and `resources/list` inside the runtime when useful. Do not cache on-chain
82
- balances, SAP agent rows, pricing, SNS ownership, quotes, or settlement
83
- state when the user expects fresh data.
92
+ and `resources/list` inside the runtime when useful. Session memory can
93
+ store operational context, receipts, signatures, and error classifications.
94
+ Do not cache on-chain balances, SAP agent rows, pricing, SNS ownership,
95
+ quotes, blockhashes, simulations, liquidity, routes, or settlement state
96
+ when the user expects fresh data.
84
97
  5. Treat `PAYMENT-RESPONSE` as the receipt bound to the tool output.
85
98
  6. If the client runtime cannot sign or attach x402 payment headers itself, use
86
99
  the local SAP MCP `sap_payments_call_paid_tool` bridge configured by the SAP
87
100
  MCP wizard instead of falling back to local stdio automatically.
88
101
 
89
- Do not use x402 for core balance reads. `sol_get_balance`,
90
- `spl-token_getBalance`, `spl-token_getTokenAccounts`, `magicblock_balance`,
91
- and `sap_x402_get_balance` are free hosted tools and should be called directly
92
- through the remote SAP MCP connection. Use `jupiter_getHoldings` only when the
93
- user needs enriched paid portfolio context. Always verify USDC and SOL balances
94
- before attempting paid calls an agent without USDC cannot make paid calls.
102
+ Do not use x402 for core balance or single-asset price readiness reads.
103
+ `sol_get_balance`, `spl-token_getBalance`, `spl-token_getTokenAccounts`,
104
+ `magicblock_balance`, `sap_x402_get_balance`, `jupiter_getPrice`,
105
+ `pyth_getPrice`, and `coingecko_getTokenPrice` are free hosted tools and should
106
+ be called directly through the remote SAP MCP connection. Use
107
+ `jupiter_getHoldings` only when the user needs enriched paid portfolio context.
108
+ Always verify USDC and SOL balances before attempting paid calls — an agent
109
+ without USDC cannot make paid calls.
95
110
 
96
111
  Before any paid tool call, use `sap_estimate_tool_cost` with the tool name to
97
112
  get the exact tier, estimated USD cost, and recommended `maxPriceUsd`. This
@@ -1,12 +0,0 @@
1
- <svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
2
- <path d="M0 64C0 28.6538 28.6538 0 64 0H192C227.346 0 256 28.6538 256 64V192C256 227.346 227.346 256 192 256H64C28.6538 256 0 227.346 0 192V64Z" fill="#08AA18"/>
3
- <g clip-path="url(#clip0_354_3823)">
4
- <path d="M32 62.9677C32 45.8647 45.8647 32 62.9677 32H193.032C210.135 32 224 45.8647 224 62.9677V193.032C224 210.135 210.135 224 193.032 224H62.9677C45.8647 224 32 210.135 32 193.032V62.9677Z" fill="#08AA18"/>
5
- <path d="M105.764 71.4325C105.367 72.4792 106.14 73.599 107.259 73.5993H129.162C130.199 73.5993 130.962 74.5712 130.717 75.5786L116.825 132.535C116.424 134.18 118.518 135.239 119.606 133.941L169.692 74.1724C169.996 73.8097 170.446 73.5993 170.919 73.5993H203.043C204.411 73.5993 205.148 75.2066 204.256 76.2439L77.1854 224H65.261L92.329 110.773C92.5694 109.767 91.8069 108.8 90.7731 108.799H52.9722C51.6232 108.799 50.8805 107.233 51.7338 106.188L112.32 32H120.719L105.764 71.4325Z" fill="white"/>
6
- </g>
7
- <defs>
8
- <clipPath id="clip0_354_3823">
9
- <rect width="192" height="192" fill="white" transform="translate(32 32)"/>
10
- </clipPath>
11
- </defs>
12
- </svg>