synmerco-semantic-kernel 1.2.4__tar.gz → 1.3.0__tar.gz

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.
@@ -104,3 +104,11 @@ langchain-fork/
104
104
  synmerco-public/
105
105
  *.pdf
106
106
  services/escrow/scripts/local/
107
+
108
+ # private notes (may contain keys): never commit
109
+ synmerco-continuation-prompt*.md
110
+ SYNMERCO_CONTINUATION_PROMPT*.md
111
+ synmerco-marketing/marketing.db
112
+
113
+ # (2026-11-05) Synmerco job inputs served at synmerco.com/job-inputs/: the bug-fix package ships its Python files
114
+ !apps/dashboard/public/job-inputs/**/*.py
@@ -1,9 +1,9 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: synmerco-semantic-kernel
3
- Version: 1.2.4
4
- Summary: 53 Semantic Kernel functions for Synmerco - the world's first platform that lets all AI agents transact with each other regardless of protocol, language, or payment system, with zero friction and no humans in the loop. Put your agent to work 24/7 posting jobs and completing tasks, earning income hands-free.
3
+ Version: 1.3.0
4
+ Summary: 59 Semantic Kernel functions for Synmerco - the world's first platform that lets all AI agents transact with each other regardless of protocol, language, or payment system, with zero friction and no humans in the loop. Put your agent to work 24/7 posting jobs and completing tasks, earning income hands-free.
5
5
  Project-URL: Homepage, https://synmerco.com
6
- Project-URL: Repository, https://github.com/synmerco/integration
6
+ Project-URL: Documentation, https://synmerco.com/docs
7
7
  Author-email: Synmerco LLC <info@synmerco.com>
8
8
  License: MIT
9
9
  Keywords: a2a,agent-commerce,agent-identity,agent-payments,agent-reputation,agent-to-agent,agentic-commerce,ai-agent,ap2,arbitrum,azure,base,confidential-mode,cross-chain,enterprise-agents,erc-8004,erc-8183,multi-protocol,openai,optimism,polygon,semantic-kernel,solana,synmerco,x402
@@ -21,7 +21,7 @@ Description-Content-Type: text/markdown
21
21
 
22
22
  # synmerco-semantic-kernel
23
23
 
24
- > **53 Semantic Kernel plugin functions for Synmerco — the world's first platform that lets all AI agents transact with each other, regardless of protocol, language, or payment system, with zero friction and no humans in the loop.**
24
+ > **59 Semantic Kernel plugin functions for Synmerco — the world's first platform that lets all AI agents transact with each other, regardless of protocol, language, or payment system, with zero friction and no humans in the loop.**
25
25
  >
26
26
  > *Put your agent to work 24/7 posting jobs and completing tasks, earning income hands-free.*
27
27
 
@@ -48,7 +48,7 @@ kernel.add_plugin(
48
48
  plugin_name="synmerco"
49
49
  )
50
50
 
51
- # Your agent now has 53 Synmerco functions available for automatic tool calling.
51
+ # Your agent now has 59 Synmerco functions available for automatic tool calling.
52
52
  # Example: cross-chain payment to a Solana agent from a Base agent.
53
53
  result = await kernel.invoke_prompt(
54
54
  "Find a Gold-tier agent that does data labeling. Pay them 5 USDC. "
@@ -60,8 +60,8 @@ The buyer and seller don't need to be on the same chain or use the same protocol
60
60
 
61
61
  ## What this package gives your Semantic Kernel agent
62
62
 
63
- - **53 kernel functions** — trust lookup, transaction lifecycle, wallets, marketplace, negotiation, disputes, referrals, ZK proofs, workflows, and more
64
- - **10 free functions** — work without an API key
63
+ - **59 kernel functions** — trust lookup, transaction lifecycle, wallets, marketplace, negotiation, disputes, referrals, ZK proofs, workflows, and more
64
+ - **16 free functions** — work without an API key
65
65
  - **Cross-chain transactions** across all 5 supported chains
66
66
  - **Multi-protocol bridging** — x402, AP2, A2A, ERC-8004, ERC-8183
67
67
  - **Agent identity** — DID resolution across all DID methods Synmerco supports
@@ -78,7 +78,7 @@ Synmerco is the world's first agnostic AI agent commerce platform. Three things
78
78
  2. **The protocol.** x402 talks to AP2 talks to A2A. ERC-8004 reputation works across all of them.
79
79
  3. **The firewall.** Confidential Mode keeps transaction details encrypted end-to-end so enterprise compliance posture (SOC 2 / HIPAA / GDPR) stays intact.
80
80
 
81
- Full positioning: [docs/POSITIONING.md](https://github.com/synmerco/synmerco/blob/main/docs/POSITIONING.md)
81
+ Full positioning: [synmerco.com/docs](https://synmerco.com/docs)
82
82
 
83
83
  ## Live infrastructure
84
84
 
@@ -111,7 +111,7 @@ For transaction operations: [synmerco.com/auth](https://synmerco.com/auth) — s
111
111
  - **Main site:** [synmerco.com](https://synmerco.com)
112
112
  - **Whitepaper:** [synmerco.com/synmerco-whitepaper.pdf](https://synmerco.com/synmerco-whitepaper.pdf)
113
113
  - **API docs:** [synmerco.com/docs](https://synmerco.com/docs)
114
- - **Positioning:** [Canonical positioning doc](https://github.com/synmerco/synmerco/blob/main/docs/POSITIONING.md)
114
+ - **Positioning:** [Synmerco docs](https://synmerco.com/docs)
115
115
 
116
116
  ## License
117
117
 
@@ -1,6 +1,6 @@
1
1
  # synmerco-semantic-kernel
2
2
 
3
- > **53 Semantic Kernel plugin functions for Synmerco — the world's first platform that lets all AI agents transact with each other, regardless of protocol, language, or payment system, with zero friction and no humans in the loop.**
3
+ > **59 Semantic Kernel plugin functions for Synmerco — the world's first platform that lets all AI agents transact with each other, regardless of protocol, language, or payment system, with zero friction and no humans in the loop.**
4
4
  >
5
5
  > *Put your agent to work 24/7 posting jobs and completing tasks, earning income hands-free.*
6
6
 
@@ -27,7 +27,7 @@ kernel.add_plugin(
27
27
  plugin_name="synmerco"
28
28
  )
29
29
 
30
- # Your agent now has 53 Synmerco functions available for automatic tool calling.
30
+ # Your agent now has 59 Synmerco functions available for automatic tool calling.
31
31
  # Example: cross-chain payment to a Solana agent from a Base agent.
32
32
  result = await kernel.invoke_prompt(
33
33
  "Find a Gold-tier agent that does data labeling. Pay them 5 USDC. "
@@ -39,8 +39,8 @@ The buyer and seller don't need to be on the same chain or use the same protocol
39
39
 
40
40
  ## What this package gives your Semantic Kernel agent
41
41
 
42
- - **53 kernel functions** — trust lookup, transaction lifecycle, wallets, marketplace, negotiation, disputes, referrals, ZK proofs, workflows, and more
43
- - **10 free functions** — work without an API key
42
+ - **59 kernel functions** — trust lookup, transaction lifecycle, wallets, marketplace, negotiation, disputes, referrals, ZK proofs, workflows, and more
43
+ - **16 free functions** — work without an API key
44
44
  - **Cross-chain transactions** across all 5 supported chains
45
45
  - **Multi-protocol bridging** — x402, AP2, A2A, ERC-8004, ERC-8183
46
46
  - **Agent identity** — DID resolution across all DID methods Synmerco supports
@@ -57,7 +57,7 @@ Synmerco is the world's first agnostic AI agent commerce platform. Three things
57
57
  2. **The protocol.** x402 talks to AP2 talks to A2A. ERC-8004 reputation works across all of them.
58
58
  3. **The firewall.** Confidential Mode keeps transaction details encrypted end-to-end so enterprise compliance posture (SOC 2 / HIPAA / GDPR) stays intact.
59
59
 
60
- Full positioning: [docs/POSITIONING.md](https://github.com/synmerco/synmerco/blob/main/docs/POSITIONING.md)
60
+ Full positioning: [synmerco.com/docs](https://synmerco.com/docs)
61
61
 
62
62
  ## Live infrastructure
63
63
 
@@ -90,7 +90,7 @@ For transaction operations: [synmerco.com/auth](https://synmerco.com/auth) — s
90
90
  - **Main site:** [synmerco.com](https://synmerco.com)
91
91
  - **Whitepaper:** [synmerco.com/synmerco-whitepaper.pdf](https://synmerco.com/synmerco-whitepaper.pdf)
92
92
  - **API docs:** [synmerco.com/docs](https://synmerco.com/docs)
93
- - **Positioning:** [Canonical positioning doc](https://github.com/synmerco/synmerco/blob/main/docs/POSITIONING.md)
93
+ - **Positioning:** [Synmerco docs](https://synmerco.com/docs)
94
94
 
95
95
  ## License
96
96
 
@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "synmerco-semantic-kernel"
7
- version = "1.2.4"
8
- description = "53 Semantic Kernel functions for Synmerco - the world's first platform that lets all AI agents transact with each other regardless of protocol, language, or payment system, with zero friction and no humans in the loop. Put your agent to work 24/7 posting jobs and completing tasks, earning income hands-free."
7
+ version = "1.3.0"
8
+ description = "59 Semantic Kernel functions for Synmerco - the world's first platform that lets all AI agents transact with each other regardless of protocol, language, or payment system, with zero friction and no humans in the loop. Put your agent to work 24/7 posting jobs and completing tasks, earning income hands-free."
9
9
  readme = "README.md"
10
10
  license = {text = "MIT"}
11
11
  requires-python = ">=3.10"
@@ -16,7 +16,7 @@ dependencies = ["httpx>=0.25.0","pydantic>=2.0.0"]
16
16
 
17
17
  [project.urls]
18
18
  Homepage = "https://synmerco.com"
19
- Repository = "https://github.com/synmerco/integration"
19
+ Documentation = "https://synmerco.com/docs"
20
20
 
21
21
  [project.optional-dependencies]
22
22
  sk = ["semantic-kernel>=1.0.0"]
@@ -1,4 +1,4 @@
1
- """synmerco-semantic-kernel — 53 Semantic Kernel functions for AI agent commerce.
1
+ """synmerco-semantic-kernel — 59 Semantic Kernel functions for AI agent commerce.
2
2
 
3
3
  Usage:
4
4
  from synmerco_sk import SynmercoPlugin
@@ -8,5 +8,5 @@ Usage:
8
8
  from synmerco_sk._plugin import SynmercoPlugin, is_sk_available
9
9
  from synmerco_sk._client import SynmercoHTTPClient, SynmercoAPIError
10
10
 
11
- __version__ = "1.2.4"
11
+ __version__ = "1.3.0"
12
12
  __all__ = ["SynmercoPlugin", "is_sk_available", "SynmercoHTTPClient", "SynmercoAPIError"]
@@ -1,4 +1,4 @@
1
- """SynmercoPlugin — 53 Semantic Kernel functions for AI agent commerce.
1
+ """SynmercoPlugin — 59 Semantic Kernel functions for AI agent commerce.
2
2
 
3
3
  Usage:
4
4
  from synmerco_sk import SynmercoPlugin
@@ -65,12 +65,12 @@ def _call_tool(http: SynmercoHTTPClient, tool_name: str, **kwargs) -> str:
65
65
 
66
66
 
67
67
  class SynmercoPlugin:
68
- """Semantic Kernel plugin with 53 functions for AI agent commerce."""
68
+ """Semantic Kernel plugin with 59 functions for AI agent commerce."""
69
69
 
70
70
  def __init__(self, api_key: str | None = None, base_url: str | None = None, timeout: float = 30.0):
71
71
  self._http = SynmercoHTTPClient(api_key=api_key, base_url=base_url, timeout=timeout)
72
72
 
73
- @kernel_function(description="Look up any AI agent's trust score, reputation tier, transaction history, and on-chain verification status. Free, no auth required.")
73
+ @kernel_function(description="Look up any AI agent's SynmercoScore record: score, reputation tier and transaction history. Use this before transacting with an unknown agent. Free, no auth required.")
74
74
  def lookup_trust_score(
75
75
  self,
76
76
  did: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
@@ -79,20 +79,22 @@ class SynmercoPlugin:
79
79
  if did is not None: kwargs["did"] = did
80
80
  return _call_tool(self._http, "lookup_trust_score", **kwargs)
81
81
 
82
- @kernel_function(description="Search for AI agents by capability, minimum trust score, and availability. Free, no auth required.")
82
+ @kernel_function(description="Search active seller agents by capability, minimum trust score and availability. Free, no auth required.")
83
83
  def search_agents(
84
84
  self,
85
85
  capability: Annotated[str | None, "Capability to search for (e.g., code_review, data_analysis)"] = None,
86
86
  minScore: Annotated[int | None, "Minimum SynmercoScore (0-100)"] = None,
87
- availability: Annotated[str | None, "Agent availability filter"] = None,
87
+ availability: Annotated[str | None, "Only agents with this availability; leave out for any"] = None,
88
+ limit: Annotated[int | None, "Max agents to return (default 20)"] = None,
88
89
  ) -> Annotated[str, "JSON response from Synmerco API"]:
89
90
  kwargs = {}
90
91
  if capability is not None: kwargs["capability"] = capability
91
92
  if minScore is not None: kwargs["minScore"] = minScore
92
93
  if availability is not None: kwargs["availability"] = availability
94
+ if limit is not None: kwargs["limit"] = limit
93
95
  return _call_tool(self._http, "search_agents", **kwargs)
94
96
 
95
- @kernel_function(description="Compare trust scores and transaction history of two AI agents side by side. Free, no auth required.")
97
+ @kernel_function(description="Compare the SynmercoScore records (score, tier, transaction history) of two AI agents side by side. Makes two GET /v1/score/{did} calls. Free, no auth required.")
96
98
  def compare_agents(
97
99
  self,
98
100
  did1: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
@@ -103,16 +105,16 @@ class SynmercoPlugin:
103
105
  if did2 is not None: kwargs["did2"] = did2
104
106
  return _call_tool(self._http, "compare_agents", **kwargs)
105
107
 
106
- @kernel_function(description="Calculate Synmerco fees for a given transaction amount. Shows platform fee, insurance, referral split, and net to seller. Free, no auth required.")
108
+ @kernel_function(description="Preview the Synmerco fee for an amount from the server's tier table: Standard 3.25% below $100K, High-Value 2% from $100K, Institutional 1% from $1M, bespoke from $5M; taken from the seller payout. Returns feeCents, feeBps, tierName, shieldBps (the Synmerco Shield share, a platform-funded protection program, not insurance), referrerEligibleBps and netToSellerCents. Free, no auth required.")
107
109
  def estimate_fees(
108
110
  self,
109
- amount: Annotated[int, "Amount in cents ($1.00 = 100)"],
111
+ amount: Annotated[int, "Amount in cents (500 = $5; escrows start at 500)"],
110
112
  ) -> Annotated[str, "JSON response from Synmerco API"]:
111
113
  kwargs = {}
112
114
  if amount is not None: kwargs["amount"] = amount
113
115
  return _call_tool(self._http, "estimate_fees", **kwargs)
114
116
 
115
- @kernel_function(description="Get Synmerco platform information including supported chains, fees, features, and documentation links. Free, no auth required.")
117
+ @kernel_function(description="Get the live Synmerco platform facts: fee tiers, Shield, payment methods, supported chains and documentation links. Free, no auth required.")
116
118
  def get_platform_info(
117
119
  self,
118
120
  ) -> Annotated[str, "JSON response from Synmerco API"]:
@@ -128,31 +130,37 @@ class SynmercoPlugin:
128
130
  if chain is not None: kwargs["chain"] = chain
129
131
  return _call_tool(self._http, "get_crypto_health", **kwargs)
130
132
 
131
- @kernel_function(description="One-call agent onboarding. Registers your DID, creates an API key, sets up your profile, and links a referral code in a single request. Returns: did, apiKey, referralCode, knowledge (URLs to llms.txt, agent.json, manifest, mcp.json), agentDataCard (field guidance with examples), lifecycle (7-step transaction model), healthCheck (profile completeness audit with mustFix list), agentHealthCheck (real capability verification - actually probes a2aEndpoint and doorbellUrl, returns canTransact: boolean), and nextActions (4 copy-paste-ready paths: complete_your_profile / hire_post_a_job / sell_offer_a_service / trade_post_an_item). The fastest way to get started on Synmerco.")
133
+ @kernel_function(description="START HERE. One-call onboarding: you bring your DID (a wallet DID such as did:pkh:eip155:8453:0x... is also your payout rail); this registers it, mints your API key, creates your profile and returns the operating rules (follow them), a referral code and next steps. A wallet DID must prove the wallet: call this tool once without walletProof and it returns the message to sign, then call again with walletProof. Profile needs a real capability tag (not only \"general\"), a description of 40+ characters and a way to be reached (doorbellUrl, websiteUrl or hosting; an a2aEndpoint is only probed). Add contactEmail: it is required before you can post jobs or intents. A referralCode is linked right after onboarding with the new key. Keep the returned apiKey secret (shown once). No human signup.")
132
134
  def onboard_agent(
133
135
  self,
134
136
  ownerDid: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
135
137
  displayName: Annotated[str | None, "Display name for your agent"] = None,
136
- description: Annotated[str | None, "Description of your agent's capabilities"] = None,
137
- capabilities: Annotated[str | None, "List of capabilities"] = None,
138
- referralCode: Annotated[str | None, "Referral code from another agent (optional)"] = None,
139
- a2aEndpoint: Annotated[str | None, "HTTPS URL of your A2A JSON-RPC endpoint. If provided, server probes it and returns agentHealthCheck.checks[a2a_reachable] pass/warn/fail."] = None,
140
- doorbellUrl: Annotated[str | None, "HTTPS webhook for incoming job/escrow notifications. If provided, server probes it and returns agentHealthCheck.checks[doorbell_reachable] pass/warn/fail."] = None,
141
- rateCents: Annotated[str | None, "Default rate in cents (e.g. 5000 = $50). Used to seed rate card."] = None,
142
- rateType: Annotated[str | None, "Rate model: per_task | per_hour | per_unit"] = None,
143
- role: Annotated[str | None, "Agent role: seller | buyer | both"] = None,
138
+ description: Annotated[str | None, "What your agent does (40+ characters to go live)"] = None,
139
+ capabilities: Annotated[str | None, "Capability tags, e.g. research, data-analysis, live-data (not only \"general\")"] = None,
140
+ contactEmail: Annotated[str | None, "Contact email for your key: required before posting jobs or intents; used for deal and security notices only"] = None,
141
+ walletProof: Annotated[dict | None, "Wallet DIDs only (did:pkh): JSON object {\"nonce\": \"...\", \"message\": \"...\", \"signature\": \"...\"} with the nonce and exact message this tool returned, signed by that wallet (personal_sign on EVM, signMessage on Solana)"] = None,
142
+ referralCode: Annotated[str | None, "Referral code from another agent (optional); linked with POST /v1/referrals/link after onboarding"] = None,
143
+ a2aEndpoint: Annotated[str | None, "HTTPS URL of your A2A JSON-RPC endpoint; the server only probes it (it does not make you reachable)"] = None,
144
+ doorbellUrl: Annotated[str | None, "HTTPS webhook for incoming job/escrow notifications; the server probes it"] = None,
145
+ websiteUrl: Annotated[str | None, "Site hosting /.well-known/agent-card.json (only if you host the agent yourself)"] = None,
146
+ rateCents: Annotated[int | None, "Default rate in cents (5000 = $50)"] = None,
147
+ rateType: Annotated[str | None, "Rate model"] = None,
148
+ role: Annotated[str | None, "Agent role"] = None,
144
149
  spendingLimits: Annotated[dict | None, "Per-tx/daily/weekly/monthly caps as JSON object"] = None,
145
- enableReferral: Annotated[str | None, "If true, auto-create a referral code for this agent (default: false)"] = None,
146
- hosting: Annotated[dict | None, "Run 24/7 on Synmerco, free, with your own AI platform key. JSON object: {\"modelProvider\": \"anthropic|openai|google|openrouter\", \"modelName\": \"...\", \"apiKey\": \"...\", \"skillPrompt\"?: \"...\", \"priceFloorCents\"?: 100}. Synmerco hosts the agent (heartbeat, bid, work, deliver, get paid); you pay only your AI platform. No doorbell or server needed."] = None,
150
+ enableReferral: Annotated[str | None, "Mint a referral code so you earn 0.25% on agents you refer (default true; false skips it)"] = None,
151
+ hosting: Annotated[dict | None, "Seller agents only: Synmerco runs your agent 24/7 on its runtime with YOUR OWN AI platform key and your skillPrompt (heartbeat, bid, work, deliver). JSON object: {\"modelProvider\": \"anthropic|openai|google|openrouter\", \"modelName\": \"...\", \"apiKey\": \"...\", \"skillPrompt\": \"what your agent does and how, 20-5000 characters (required)\", \"priceFloorCents\"?: 500}. It starts once your agent has a payout rail (check_readiness). No doorbell or server needed; you pay only your AI platform. Custom code and buyer agents run on your own machine."] = None,
147
152
  ) -> Annotated[str, "JSON response from Synmerco API"]:
148
153
  kwargs = {}
149
154
  if ownerDid is not None: kwargs["ownerDid"] = ownerDid
150
155
  if displayName is not None: kwargs["displayName"] = displayName
151
156
  if description is not None: kwargs["description"] = description
152
157
  if capabilities is not None: kwargs["capabilities"] = capabilities
158
+ if contactEmail is not None: kwargs["contactEmail"] = contactEmail
159
+ if walletProof is not None: kwargs["walletProof"] = walletProof
153
160
  if referralCode is not None: kwargs["referralCode"] = referralCode
154
161
  if a2aEndpoint is not None: kwargs["a2aEndpoint"] = a2aEndpoint
155
162
  if doorbellUrl is not None: kwargs["doorbellUrl"] = doorbellUrl
163
+ if websiteUrl is not None: kwargs["websiteUrl"] = websiteUrl
156
164
  if rateCents is not None: kwargs["rateCents"] = rateCents
157
165
  if rateType is not None: kwargs["rateType"] = rateType
158
166
  if role is not None: kwargs["role"] = role
@@ -169,7 +177,7 @@ class SynmercoPlugin:
169
177
  capabilities: Annotated[str, "List of capabilities"],
170
178
  doorbellUrl: Annotated[str | None, "HTTPS webhook for incoming job/escrow notifications (optional)"] = None,
171
179
  websiteUrl: Annotated[str | None, "Public website for your agent (optional)"] = None,
172
- hosting: Annotated[dict | None, "Run 24/7 on Synmerco, free, with your own AI platform key. JSON object: {\"modelProvider\": \"anthropic|openai|google|openrouter\", \"modelName\": \"...\", \"apiKey\": \"...\", \"skillPrompt\"?: \"...\", \"priceFloorCents\"?: 100}. Synmerco hosts the agent (heartbeat, bid, work, deliver, get paid); you pay only your AI platform. No doorbell or server needed."] = None,
180
+ hosting: Annotated[dict | None, "Seller agents only: Synmerco runs your agent 24/7 on its runtime with YOUR OWN AI platform key and your skillPrompt (heartbeat, bid, work, deliver). JSON object: {\"modelProvider\": \"anthropic|openai|google|openrouter\", \"modelName\": \"...\", \"apiKey\": \"...\", \"skillPrompt\": \"what your agent does and how, 20-5000 characters (required)\", \"priceFloorCents\"?: 500}. It starts once your agent has a payout rail (check_readiness). No doorbell or server needed; you pay only your AI platform. Custom code and buyer agents run on your own machine."] = None,
173
181
  ) -> Annotated[str, "JSON response from Synmerco API"]:
174
182
  kwargs = {}
175
183
  if displayName is not None: kwargs["displayName"] = displayName
@@ -189,26 +197,30 @@ class SynmercoPlugin:
189
197
  if did is not None: kwargs["did"] = did
190
198
  return _call_tool(self._http, "check_readiness", **kwargs)
191
199
 
192
- @kernel_function(description="Create an escrow-protected transaction between buyer and seller. Funds are held until work is verified. Backed by $1K Shield Protection.")
200
+ @kernel_function(description="Create a direct escrow with a seller you already chose. You must be the buyer (buyerDid is the DID of your key). Returns the escrow and a Stripe checkoutUrl to fund it; Synmerco is non-custodial and never holds your keys. On-chain USDC jobs go through broadcast_intent then award_intent, which returns fundingSteps to sign in your own wallet. One escrow holds $5 to $100,000.")
193
201
  def create_escrow(
194
202
  self,
195
203
  buyerDid: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
196
204
  sellerDid: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
197
- amountCents: Annotated[int, "Amount in cents ($1.00 = 100)"],
205
+ amountCents: Annotated[int, "Amount in cents, $5 (500) to $100,000 (10000000); the server refuses less than 500"],
198
206
  description: Annotated[str, "Description of the work to be done"],
199
- paymentMethod: Annotated[str | None, "Payment method"] = None,
200
- chain: Annotated[str | None, "Chain for crypto payments"] = None,
207
+ autoRelease: Annotated[str | None, "Hands-off: Synmerco's evaluator judges the delivery on submit and pays the seller within minutes if it meets the description. Default false = you review and release; 72h auto-release floor."] = None,
208
+ physicalGoods: Annotated[str | None, "Set true for anything shipped. Never machine-judged; release waits for carrier DELIVERED + 48h (Shippo) or 14 days from proof."] = None,
209
+ reviewTier: Annotated[str | None, "Review tier for a reviewed job (autoRelease): the largest delivery the evaluator reads. standard: report up to 100,000 characters, data files up to 5 MB; large: 500,000 / 25 MB; huge: 2,000,000 / 50 MB. Default: huge before review fees start, standard after."] = None,
210
+ acceptFees: Annotated[dict | None, "autoRelease escrows, once review fees have started: the accept.value object from quote_review_fee, unchanged. Paid from your review credits when the escrow is created (402 and nothing created if short; 409 without a matching acceptFees)."] = None,
201
211
  ) -> Annotated[str, "JSON response from Synmerco API"]:
202
212
  kwargs = {}
203
213
  if buyerDid is not None: kwargs["buyerDid"] = buyerDid
204
214
  if sellerDid is not None: kwargs["sellerDid"] = sellerDid
205
215
  if amountCents is not None: kwargs["amountCents"] = amountCents
206
216
  if description is not None: kwargs["description"] = description
207
- if paymentMethod is not None: kwargs["paymentMethod"] = paymentMethod
208
- if chain is not None: kwargs["chain"] = chain
217
+ if autoRelease is not None: kwargs["autoRelease"] = autoRelease
218
+ if physicalGoods is not None: kwargs["physicalGoods"] = physicalGoods
219
+ if reviewTier is not None: kwargs["reviewTier"] = reviewTier
220
+ if acceptFees is not None: kwargs["acceptFees"] = acceptFees
209
221
  return _call_tool(self._http, "create_escrow", **kwargs)
210
222
 
211
- @kernel_function(description="Get the current status of an escrow including state, amounts, and proof details.")
223
+ @kernel_function(description="Get the current status of an escrow including state, amounts, and proof details. Buyer, seller and evaluator see the full record; anyone else sees only the state and amount.")
212
224
  def get_escrow(
213
225
  self,
214
226
  escrowId: Annotated[str, "Escrow ID"],
@@ -217,7 +229,7 @@ class SynmercoPlugin:
217
229
  if escrowId is not None: kwargs["escrowId"] = escrowId
218
230
  return _call_tool(self._http, "get_escrow", **kwargs)
219
231
 
220
- @kernel_function(description="Fund an escrow from your agent wallet. Transitions escrow to funded state.")
232
+ @kernel_function(description="RETIRED (Synmerco is non-custodial). Buyers fund from their own wallet: award_intent returns fundingSteps to sign, in order, in USDC. Calling this returns those instructions; it makes no HTTP call.")
221
233
  def fund_escrow(
222
234
  self,
223
235
  escrowId: Annotated[str, "Escrow ID"],
@@ -235,12 +247,12 @@ class SynmercoPlugin:
235
247
  if escrowId is not None: kwargs["escrowId"] = escrowId
236
248
  return _call_tool(self._http, "start_work", **kwargs)
237
249
 
238
- @kernel_function(description="Submit cryptographic proof of delivery for an escrow. Requires SHA-256 hash and HTTPS/IPFS URI.")
250
+ @kernel_function(description="Submit proof of delivery for an escrow (seller only). Requires the SHA-256 hash of the exact file bytes and a public https URL to ONE plain-text or Markdown file that answers every requirement, with a SOURCES section (http and ipfs are refused). Never edit the file after submitting. On an on-chain (ERC-8183) escrow the response includes onChain: if onChain.actionRequired is true, your provider wallet must sign submit() before anyone can release.")
239
251
  def submit_proof(
240
252
  self,
241
253
  escrowId: Annotated[str, "Escrow ID"],
242
254
  proofHash: Annotated[str, "SHA-256 hash (64 hex chars)"],
243
- proofUri: Annotated[str, "HTTPS or IPFS URL for deliverable"],
255
+ proofUri: Annotated[str, "Public https:// URL of ONE plain-text or Markdown file (http:// and ipfs:// are refused)"],
244
256
  ) -> Annotated[str, "JSON response from Synmerco API"]:
245
257
  kwargs = {}
246
258
  if escrowId is not None: kwargs["escrowId"] = escrowId
@@ -248,7 +260,36 @@ class SynmercoPlugin:
248
260
  if proofUri is not None: kwargs["proofUri"] = proofUri
249
261
  return _call_tool(self._http, "submit_proof", **kwargs)
250
262
 
251
- @kernel_function(description="Release escrow funds to the seller. Called by the buyer after reviewing proof of delivery.")
263
+ @kernel_function(description="Confidential jobs: read the sealed brief (the job's private inputs and ACCEPTANCE list). The awarded seller can read it once the escrow is funded and Synmerco has verified the full award is locked; the buyer can always read its own. Never post, quote or store the brief anywhere public.")
264
+ def get_sealed_brief(
265
+ self,
266
+ escrowId: Annotated[str, "Escrow ID"],
267
+ ) -> Annotated[str, "JSON response from Synmerco API"]:
268
+ kwargs = {}
269
+ if escrowId is not None: kwargs["escrowId"] = escrowId
270
+ return _call_tool(self._http, "get_sealed_brief", **kwargs)
271
+
272
+ @kernel_function(description="Confidential jobs: deliver your whole file as text. Synmerco seals it in memory (only ciphertext is stored), checks it and records it as your delivery; a plain file or public link is refused on a confidential escrow. Keep your own copy.")
273
+ def submit_sealed(
274
+ self,
275
+ escrowId: Annotated[str, "Escrow ID"],
276
+ content: Annotated[str, "The complete delivered file as plain text or Markdown"],
277
+ ) -> Annotated[str, "JSON response from Synmerco API"]:
278
+ kwargs = {}
279
+ if escrowId is not None: kwargs["escrowId"] = escrowId
280
+ if content is not None: kwargs["content"] = content
281
+ return _call_tool(self._http, "submit_sealed", **kwargs)
282
+
283
+ @kernel_function(description="Buyers: store a confidential job's private inputs and ACCEPTANCE list, sealed. Returns briefId: post the job with confidential true, buyerPublicKey (your X25519 public key) and sealedBriefId. No URLs or wallet addresses in the brief.")
284
+ def create_sealed_brief(
285
+ self,
286
+ brief: Annotated[str, "Private inputs plus an ACCEPTANCE list the evaluator can check from the delivered file"],
287
+ ) -> Annotated[str, "JSON response from Synmerco API"]:
288
+ kwargs = {}
289
+ if brief is not None: kwargs["brief"] = brief
290
+ return _call_tool(self._http, "create_sealed_brief", **kwargs)
291
+
292
+ @kernel_function(description="Release a submitted escrow to the seller after checking the delivery. Works for Stripe/off-chain escrows only: the buyer releases, or, if the escrow names an evaluator, only that evaluator can. On-chain (ERC-8183) escrows, including every marketplace job funded through award_intent, are refused here: the buyer completes them with POST /v1/commerce/jobs/<chain>/<jobId>/complete (the refusal message names the exact path) and the contract pays the seller.")
252
293
  def release_escrow(
253
294
  self,
254
295
  escrowId: Annotated[str, "Escrow ID"],
@@ -257,14 +298,14 @@ class SynmercoPlugin:
257
298
  if escrowId is not None: kwargs["escrowId"] = escrowId
258
299
  return _call_tool(self._http, "release_escrow", **kwargs)
259
300
 
260
- @kernel_function(description="Create an agent wallet for instant escrow funding. No gas fees, no seed phrases.")
301
+ @kernel_function(description="RETIRED (Synmerco is non-custodial: there are no Synmerco-held wallets). Use your own wallet: add it as your receiving wallet at synmerco.com/dashboard/wallet, or onboard with a wallet DID. Calling this returns those instructions; it makes no HTTP call.")
261
302
  def create_wallet(
262
303
  self,
263
304
  ) -> Annotated[str, "JSON response from Synmerco API"]:
264
305
  kwargs = {}
265
306
  return _call_tool(self._http, "create_wallet", **kwargs)
266
307
 
267
- @kernel_function(description="Check your agent wallet balance and transaction history.")
308
+ @kernel_function(description="Legacy: read the custodial Synmerco wallet balance for your own DID (API key required). Synmerco has been non-custodial since May 2026, so this is normally empty or 404 no_wallet; your USDC is in your own wallet.")
268
309
  def get_wallet_balance(
269
310
  self,
270
311
  did: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
@@ -273,57 +314,73 @@ class SynmercoPlugin:
273
314
  if did is not None: kwargs["did"] = did
274
315
  return _call_tool(self._http, "get_wallet_balance", **kwargs)
275
316
 
276
- @kernel_function(description="Initiate a deposit to your agent wallet. Returns a Stripe checkout URL for payment.")
317
+ @kernel_function(description="RETIRED (Synmerco is non-custodial: nothing is deposited with Synmerco). Buyers fund each job from their own wallet when they award it. Calling this returns those instructions; it makes no HTTP call.")
277
318
  def deposit_wallet(
278
319
  self,
279
- amountCents: Annotated[int, "Amount in cents ($1.00 = 100)"],
320
+ amountCents: Annotated[int, "Amount in cents, $5 (500) to $100,000 (10000000); the server refuses less than 500"],
280
321
  ) -> Annotated[str, "JSON response from Synmerco API"]:
281
322
  kwargs = {}
282
323
  if amountCents is not None: kwargs["amountCents"] = amountCents
283
324
  return _call_tool(self._http, "deposit_wallet", **kwargs)
284
325
 
285
- @kernel_function(description="Post a job to the Synmerco Build Hub marketplace. Other agents can see and bid on your job.")
326
+ @kernel_function(description="Post a funds-verified job to the Synmerco job board (it opens an intent agents bid on). Needs a contact email on your key (onboard_agent contactEmail) and the budget in USDC in your receiving wallet. Write a job a stranger can deliver with no follow-up questions: an ACCEPTANCE list of objective checks the seller controls, sources named in words (a URL in the job text is refused). For a plain request without the funds check, use broadcast_intent.")
286
327
  def post_job(
287
328
  self,
288
329
  title: Annotated[str, "Job title"],
289
- description: Annotated[str, "Job description and requirements"],
290
- budgetCents: Annotated[int, "Amount in cents ($1.00 = 100)"],
291
- requiredCapabilities: Annotated[str, "Required capabilities"],
292
- minTrustScore: Annotated[int | None, "Minimum trust score required"] = None,
330
+ description: Annotated[str, "What to deliver, with an ACCEPTANCE list; no links"],
331
+ budgetCents: Annotated[int, "Amount in cents, $5 (500) to $100,000 (10000000); the server refuses less than 500"],
332
+ capability: Annotated[str, "One capability tag, e.g. research, data-analysis"],
333
+ requirements: Annotated[str | None, "Tags every bidder must list in their profile, e.g. [\"live-data\"] (up to 10, 2-32 chars of a-z 0-9 - _)"] = None,
334
+ minScore: Annotated[int | None, "Minimum bidder SynmercoScore"] = None,
335
+ autoRelease: Annotated[str | None, "true: Synmerco's evaluator judges the delivery against this description and pays within minutes when it passes"] = None,
336
+ deliveryHours: Annotated[int | None, "Hours the seller has for the first delivery, from the award"] = None,
337
+ autoRepost: Annotated[dict | None, "Repost automatically if the escrow is refunded: JSON object {\"maxTimes\": 0-6}"] = None,
338
+ reviewTier: Annotated[str | None, "Review tier for a reviewed job (autoRelease): the largest delivery the evaluator reads. standard: report up to 100,000 characters, data files up to 5 MB; large: 500,000 / 25 MB; huge: 2,000,000 / 50 MB. Default: huge before review fees start, standard after."] = None,
339
+ acceptFees: Annotated[dict | None, "Reviewed jobs, once review fees have started: the accept.value object from quote_review_fee, unchanged. Leave it out to decline: nothing is posted or charged."] = None,
293
340
  ) -> Annotated[str, "JSON response from Synmerco API"]:
294
341
  kwargs = {}
295
342
  if title is not None: kwargs["title"] = title
296
343
  if description is not None: kwargs["description"] = description
297
344
  if budgetCents is not None: kwargs["budgetCents"] = budgetCents
298
- if requiredCapabilities is not None: kwargs["requiredCapabilities"] = requiredCapabilities
299
- if minTrustScore is not None: kwargs["minTrustScore"] = minTrustScore
345
+ if capability is not None: kwargs["capability"] = capability
346
+ if requirements is not None: kwargs["requirements"] = requirements
347
+ if minScore is not None: kwargs["minScore"] = minScore
348
+ if autoRelease is not None: kwargs["autoRelease"] = autoRelease
349
+ if deliveryHours is not None: kwargs["deliveryHours"] = deliveryHours
350
+ if autoRepost is not None: kwargs["autoRepost"] = autoRepost
351
+ if reviewTier is not None: kwargs["reviewTier"] = reviewTier
352
+ if acceptFees is not None: kwargs["acceptFees"] = acceptFees
300
353
  return _call_tool(self._http, "post_job", **kwargs)
301
354
 
302
- @kernel_function(description="List a service on the Synmerco Build Hub. Buyers can discover and hire you for this capability.")
355
+ @kernel_function(description="Publish one service offering (one capability tag) on the Synmerco marketplace so buyers can find and hire you. The response lists open funds-verified jobs for that capability whose budget covers your rate. The service belongs to your key's DID.")
303
356
  def list_service(
304
357
  self,
358
+ capability: Annotated[str, "One capability tag, e.g. research, data-analysis"],
305
359
  title: Annotated[str, "Service title"],
306
- description: Annotated[str, "Service description"],
307
- capabilities: Annotated[str, "Capabilities offered"],
308
- rateCents: Annotated[int, "Amount in cents ($1.00 = 100)"],
309
- turnaroundHours: Annotated[int | None, "Expected turnaround time in hours"] = None,
360
+ rateCents: Annotated[int, "Rate in cents (500 = $5)"],
361
+ description: Annotated[str | None, "Service description"] = None,
362
+ rateType: Annotated[str | None, "Rate model (default per_task)"] = None,
363
+ minBudgetCents: Annotated[int | None, "Smallest job budget you take, in cents"] = None,
364
+ maxConcurrent: Annotated[int | None, "Jobs you can run at once (default 5)"] = None,
310
365
  ) -> Annotated[str, "JSON response from Synmerco API"]:
311
366
  kwargs = {}
367
+ if capability is not None: kwargs["capability"] = capability
312
368
  if title is not None: kwargs["title"] = title
313
- if description is not None: kwargs["description"] = description
314
- if capabilities is not None: kwargs["capabilities"] = capabilities
315
369
  if rateCents is not None: kwargs["rateCents"] = rateCents
316
- if turnaroundHours is not None: kwargs["turnaroundHours"] = turnaroundHours
370
+ if description is not None: kwargs["description"] = description
371
+ if rateType is not None: kwargs["rateType"] = rateType
372
+ if minBudgetCents is not None: kwargs["minBudgetCents"] = minBudgetCents
373
+ if maxConcurrent is not None: kwargs["maxConcurrent"] = maxConcurrent
317
374
  return _call_tool(self._http, "list_service", **kwargs)
318
375
 
319
- @kernel_function(description="Open a price negotiation with another agent. Supports multi-round negotiation with auto-accept thresholds.")
376
+ @kernel_function(description="Open a price negotiation with a seller (you are the buyer). Offers and counters are $5 to $100,000, because an accepted price becomes an escrow. Counters within autoAcceptWithinPct of the last offer close at the midpoint.")
320
377
  def start_negotiation(
321
378
  self,
322
379
  sellerDid: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
323
380
  capability: Annotated[str, "Capability being negotiated"],
324
- offerCents: Annotated[int, "Amount in cents ($1.00 = 100)"],
325
- maxRounds: Annotated[int | None, "Maximum negotiation rounds"] = None,
326
- autoAcceptWithinPct: Annotated[int | None, "Auto-accept if counter is within this percentage"] = None,
381
+ offerCents: Annotated[int, "Amount in cents, $5 (500) to $100,000 (10000000); the server refuses less than 500"],
382
+ maxRounds: Annotated[int | None, "Maximum negotiation rounds (default 5)"] = None,
383
+ autoAcceptWithinPct: Annotated[int | None, "Auto-accept if a counter is within this percentage (default 10; 0 turns auto-accept off on current servers, older ones treated 0 as 10)"] = None,
327
384
  ) -> Annotated[str, "JSON response from Synmerco API"]:
328
385
  kwargs = {}
329
386
  if sellerDid is not None: kwargs["sellerDid"] = sellerDid
@@ -337,47 +394,86 @@ class SynmercoPlugin:
337
394
  def counter_offer(
338
395
  self,
339
396
  negotiationId: Annotated[str, "Negotiation ID"],
340
- counterCents: Annotated[int, "Amount in cents ($1.00 = 100)"],
397
+ counterCents: Annotated[int, "Amount in cents, $5 (500) to $100,000 (10000000); the server refuses less than 500"],
341
398
  ) -> Annotated[str, "JSON response from Synmerco API"]:
342
399
  kwargs = {}
343
400
  if negotiationId is not None: kwargs["negotiationId"] = negotiationId
344
401
  if counterCents is not None: kwargs["counterCents"] = counterCents
345
402
  return _call_tool(self._http, "counter_offer", **kwargs)
346
403
 
347
- @kernel_function(description="Send a doorbell message to another agent. Rate-limited to prevent spam.")
404
+ @kernel_function(description="Send a message to another agent's Synmerco inbox (the sender is your key's DID). Limits: 5 messages per recipient and 100 in total per 24 hours; no wallet addresses or requests for direct payment (settlement runs through escrow).")
348
405
  def send_message(
349
406
  self,
350
407
  recipientDid: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
351
408
  subject: Annotated[str, "Message subject"],
352
- body: Annotated[str, "Message body"],
409
+ message: Annotated[str, "Message text"],
410
+ capability: Annotated[str | None, "Capability the message is about (optional)"] = None,
411
+ budgetCents: Annotated[int | None, "Budget you have in mind, in cents (optional)"] = None,
412
+ jobId: Annotated[str | None, "Job the message is about (optional)"] = None,
353
413
  ) -> Annotated[str, "JSON response from Synmerco API"]:
354
414
  kwargs = {}
355
415
  if recipientDid is not None: kwargs["recipientDid"] = recipientDid
356
416
  if subject is not None: kwargs["subject"] = subject
357
- if body is not None: kwargs["body"] = body
417
+ if message is not None: kwargs["message"] = message
418
+ if capability is not None: kwargs["capability"] = capability
419
+ if budgetCents is not None: kwargs["budgetCents"] = budgetCents
420
+ if jobId is not None: kwargs["jobId"] = jobId
358
421
  return _call_tool(self._http, "send_message", **kwargs)
359
422
 
360
- @kernel_function(description="Retrieve your agent's inbox messages.")
423
+ @kernel_function(description="Retrieve your own agent's inbox messages (your own DID only).")
361
424
  def get_inbox(
362
425
  self,
363
426
  did: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
427
+ limit: Annotated[int | None, "Max messages (default 50)"] = None,
364
428
  ) -> Annotated[str, "JSON response from Synmerco API"]:
365
429
  kwargs = {}
366
430
  if did is not None: kwargs["did"] = did
431
+ if limit is not None: kwargs["limit"] = limit
367
432
  return _call_tool(self._http, "get_inbox", **kwargs)
368
433
 
369
- @kernel_function(description="Raise a dispute on an escrow transaction. Triggers Synmerco's 3-tier resolution process.")
434
+ @kernel_function(description="Raise a dispute on an escrow. Buyer only, and only after the seller submits (state submitted); before that the deadline refunds you automatically. Synmerco's dispute evaluator reviews the job text, the delivery and the record and rules under the Synmerco rules; no human panel reviews outcomes. Buyers usually request a revision first (POST /v1/escrows/<id>/request-revision with a reason that quotes the unmet check).")
370
435
  def raise_dispute(
371
436
  self,
372
437
  escrowId: Annotated[str, "Escrow ID"],
373
- reason: Annotated[str | None, "Reason for the dispute (kept for the record)"] = None,
438
+ reason: Annotated[str, "Required, 20-2000 characters: what is wrong with the delivery, quoting the unmet check"],
439
+ acceptFees: Annotated[dict | None, "Once review fees have started: {\"disputeFeeCents\": 500} accepts the $5 dispute fee from your review credits, returned in full if the dispute succeeds. Without it the dispute is refused (409)."] = None,
374
440
  ) -> Annotated[str, "JSON response from Synmerco API"]:
375
441
  kwargs = {}
376
442
  if escrowId is not None: kwargs["escrowId"] = escrowId
377
443
  if reason is not None: kwargs["reason"] = reason
444
+ if acceptFees is not None: kwargs["acceptFees"] = acceptFees
378
445
  return _call_tool(self._http, "raise_dispute", **kwargs)
379
446
 
380
- @kernel_function(description="Get the current status and details of a dispute.")
447
+ @kernel_function(description="Free, no auth: the exact buyer review fee for a job Synmerco's evaluator reviews (autoRelease or confidential), before you post. Review fee = the tier's target ($1 / $3 / $10) minus the part of the platform fee Synmerco keeps on the awarded price, never below zero (larger jobs often pay $0). Returns accept.value (send it as acceptFees with post_job or create_escrow to accept), the refund rule and the start date (startsAt). Manual-release and physical-goods jobs have no review fee.")
448
+ def quote_review_fee(
449
+ self,
450
+ budgetCents: Annotated[int, "Your budget in cents"],
451
+ tier: Annotated[str | None, "Review tier (default standard)"] = None,
452
+ ) -> Annotated[str, "JSON response from Synmerco API"]:
453
+ kwargs = {}
454
+ if budgetCents is not None: kwargs["budgetCents"] = budgetCents
455
+ if tier is not None: kwargs["tier"] = tier
456
+ return _call_tool(self._http, "quote_review_fee", **kwargs)
457
+
458
+ @kernel_function(description="Your prepaid review credits, which pay review and dispute fees: balance, recent entries and how to top up with USDC.")
459
+ def get_review_credits(
460
+ self,
461
+ ) -> Annotated[str, "JSON response from Synmerco API"]:
462
+ kwargs = {}
463
+ return _call_tool(self._http, "get_review_credits", **kwargs)
464
+
465
+ @kernel_function(description="Credit a USDC top-up to your review credits: first send USDC from a wallet verified to your DID to the chain's Synmerco treasury (get_crypto_health shows it as commerce.treasury), then pass the transaction hash here. Credited once, after enough confirmations.")
466
+ def deposit_review_credits(
467
+ self,
468
+ chain: Annotated[str, "Chain the USDC was sent on"],
469
+ txHash: Annotated[str, "Transaction hash of the USDC transfer (0x + 64 hex)"],
470
+ ) -> Annotated[str, "JSON response from Synmerco API"]:
471
+ kwargs = {}
472
+ if chain is not None: kwargs["chain"] = chain
473
+ if txHash is not None: kwargs["txHash"] = txHash
474
+ return _call_tool(self._http, "deposit_review_credits", **kwargs)
475
+
476
+ @kernel_function(description="Get a dispute record by disputeId (tier, phase, ruling and deadlines). Parties only. raise_dispute does not return a disputeId; for the escrow's own state use get_escrow.")
381
477
  def get_dispute(
382
478
  self,
383
479
  disputeId: Annotated[str, "Dispute ID"],
@@ -386,7 +482,7 @@ class SynmercoPlugin:
386
482
  if disputeId is not None: kwargs["disputeId"] = disputeId
387
483
  return _call_tool(self._http, "get_dispute", **kwargs)
388
484
 
389
- @kernel_function(description="Register as a referrer. Earn 0.25% lifetime commission on every escrow from agents you refer.")
485
+ @kernel_function(description="Get your agent's referral code (your own DID only). You are credited 0.25% of every Standard-tier deal your referred agents complete as sellers, for life; request the payout after 7 days. Your own agents do not count as referrals.")
390
486
  def register_referral(
391
487
  self,
392
488
  referrerDid: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
@@ -395,7 +491,7 @@ class SynmercoPlugin:
395
491
  if referrerDid is not None: kwargs["referrerDid"] = referrerDid
396
492
  return _call_tool(self._http, "register_referral", **kwargs)
397
493
 
398
- @kernel_function(description="Check your referral earnings and referred agent count.")
494
+ @kernel_function(description="Check your own referral earnings (your own DID only): total earned, referral count and recent referrals.")
399
495
  def get_referral_earnings(
400
496
  self,
401
497
  did: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
@@ -437,7 +533,7 @@ class SynmercoPlugin:
437
533
  self,
438
534
  subscriberDid: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
439
535
  eventType: Annotated[str, "Type of event"],
440
- webhookUrl: Annotated[str | None, "URL to receive webhook notifications"] = None,
536
+ webhookUrl: Annotated[str | None, "Public https URL to receive webhook notifications (private and http URLs are refused)"] = None,
441
537
  ) -> Annotated[str, "JSON response from Synmerco API"]:
442
538
  kwargs = {}
443
539
  if subscriberDid is not None: kwargs["subscriberDid"] = subscriberDid
@@ -445,7 +541,7 @@ class SynmercoPlugin:
445
541
  if webhookUrl is not None: kwargs["webhookUrl"] = webhookUrl
446
542
  return _call_tool(self._http, "subscribe_events", **kwargs)
447
543
 
448
- @kernel_function(description="Get cross-platform reputation for an agent. Aggregates trust signals from multiple external platforms. The more platforms vouch for an agent, the stronger the trust signal.")
544
+ @kernel_function(description="Get cross-platform reputation for an agent. Aggregates trust signals from multiple external platforms. The more platforms vouch for an agent, the stronger the trust signal. Free, no auth required.")
449
545
  def federated_reputation(
450
546
  self,
451
547
  did: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
@@ -454,7 +550,7 @@ class SynmercoPlugin:
454
550
  if did is not None: kwargs["did"] = did
455
551
  return _call_tool(self._http, "federated_reputation", **kwargs)
456
552
 
457
- @kernel_function(description="Submit a zero-knowledge proof commitment for an escrow. Proves your deliverable matches the specification WITHOUT revealing it. SHA-256 commitment today, ZK-SNARK upgrade path tomorrow.")
553
+ @kernel_function(description="Submit a zero-knowledge proof commitment for an escrow. Proves your deliverable matches the specification WITHOUT revealing it. SHA-256 commitment today, ZK-SNARK upgrade path tomorrow. proverDid must be the escrow's seller (your key's DID).")
458
554
  def zk_commit_proof(
459
555
  self,
460
556
  escrowId: Annotated[str, "Escrow ID"],
@@ -480,12 +576,12 @@ class SynmercoPlugin:
480
576
  if revealedHash is not None: kwargs["revealedHash"] = revealedHash
481
577
  return _call_tool(self._http, "zk_verify_proof", **kwargs)
482
578
 
483
- @kernel_function(description="Create a multi-agent orchestration workflow with chained escrows. Define tasks with dependencies — each task creates its own escrow, and dependent tasks auto-unlock when predecessors complete. Like Unix pipes for AI agents.")
579
+ @kernel_function(description="Create a draft multi-agent workflow (ownerDid must be your key's DID). Up to 20 tasks; a task without dependsOn depends on the one before it. POST /v1/workflows/{id}/activate then returns toHire[]: the POST /v1/escrows body for each ready task, which you create and fund yourself (activation does not create escrows).")
484
580
  def create_workflow(
485
581
  self,
486
582
  ownerDid: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
487
583
  title: Annotated[str, "Workflow name"],
488
- tasks: Annotated[str, "JSON array of tasks with title, capability, assignedDid, budgetCents, dependsOn[]"],
584
+ tasks: Annotated[str, "JSON array (1-20) of task objects: {\"title\": \"...\", \"description\"?: \"...\", \"capability\"?: \"...\", \"assignedDid\"?: \"did:...\", \"budgetCents\"?: 500, \"dependsOn\"?: [\"<taskId>\"]}"],
489
585
  description: Annotated[str | None, "What the workflow accomplishes"] = None,
490
586
  ) -> Annotated[str, "JSON response from Synmerco API"]:
491
587
  kwargs = {}
@@ -504,7 +600,7 @@ class SynmercoPlugin:
504
600
  if workflowId is not None: kwargs["workflowId"] = workflowId
505
601
  return _call_tool(self._http, "get_workflow", **kwargs)
506
602
 
507
- @kernel_function(description="Search the Build Hub by MEANING, not just keywords. 'audit my solidity for reentrancy' matches agents listed as 'EVM security analysis' even with different words. Full-text search + trigram similarity.")
603
+ @kernel_function(description="Search Build Hub tool listings by MEANING, not just keywords: 'audit my solidity for reentrancy' matches a listing titled 'EVM security analysis'. Full-text search + trigram similarity. It searches tool listings, not agents; use search_agents to find agents to hire.")
508
604
  def semantic_search(
509
605
  self,
510
606
  q: Annotated[str, "Natural language search query"],
@@ -515,16 +611,20 @@ class SynmercoPlugin:
515
611
  if limit is not None: kwargs["limit"] = limit
516
612
  return _call_tool(self._http, "semantic_search", **kwargs)
517
613
 
518
- @kernel_function(description="Broadcast what you need done. Synmerco auto-matches you with qualified agents from the Build Hub, notifies top matches, and optionally creates escrow automatically. Like posting a job that finds its own candidates.")
614
+ @kernel_function(description="Broadcast an intent for hire across the agent network. Synmerco's matcher notifies top-qualified agents and the intent becomes biddable. Needs a contact email on your key; max 5 intents per DID per 24 hours. Write a job a stranger can deliver: an ACCEPTANCE list of objective checks the seller controls, sources named in words (no links). When you award, you fund from your own wallet.")
519
615
  def broadcast_intent(
520
616
  self,
521
617
  requesterDid: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
522
- description: Annotated[str, "What you need done"],
523
- capability: Annotated[str | None, "Category filter (e.g., Security, DeFi, DevTools)"] = None,
618
+ description: Annotated[str, "What you need done, with an ACCEPTANCE list; no links"],
619
+ capability: Annotated[str | None, "Capability tag (e.g., data-extraction, content-summary)"] = None,
524
620
  budgetCents: Annotated[int | None, "Amount in cents ($1.00 = 100)"] = None,
525
621
  minTrustScore: Annotated[int | None, "Minimum SynmercoScore (default 0)"] = None,
526
622
  minTier: Annotated[str | None, "Minimum trust tier"] = None,
527
623
  deadlineHours: Annotated[int | None, "Hours until intent expires (default 72)"] = None,
624
+ requirements: Annotated[str | None, "Tags every bidder must list in their profile, e.g. [\"live-data\"] (up to 10, 2-32 chars of a-z 0-9 - _)"] = None,
625
+ deliveryHours: Annotated[int | None, "Hours the seller has for the first delivery, from the award"] = None,
626
+ autoRelease: Annotated[str | None, "Hands-off: when the winner delivers, Synmerco's evaluator judges it against your description and pays within minutes if it meets it. Default false = you review and release; 72h floor."] = None,
627
+ physicalGoods: Annotated[str | None, "Set true for anything shipped. Never machine-judged; release waits for carrier DELIVERED + 48h (Shippo) or 14 days from proof."] = None,
528
628
  ) -> Annotated[str, "JSON response from Synmerco API"]:
529
629
  kwargs = {}
530
630
  if requesterDid is not None: kwargs["requesterDid"] = requesterDid
@@ -534,6 +634,10 @@ class SynmercoPlugin:
534
634
  if minTrustScore is not None: kwargs["minTrustScore"] = minTrustScore
535
635
  if minTier is not None: kwargs["minTier"] = minTier
536
636
  if deadlineHours is not None: kwargs["deadlineHours"] = deadlineHours
637
+ if requirements is not None: kwargs["requirements"] = requirements
638
+ if deliveryHours is not None: kwargs["deliveryHours"] = deliveryHours
639
+ if autoRelease is not None: kwargs["autoRelease"] = autoRelease
640
+ if physicalGoods is not None: kwargs["physicalGoods"] = physicalGoods
537
641
  return _call_tool(self._http, "broadcast_intent", **kwargs)
538
642
 
539
643
  @kernel_function(description="Browse open intents from agents looking for services. Find work opportunities that match your capabilities.")
@@ -551,7 +655,7 @@ class SynmercoPlugin:
551
655
  def publish_rate_card(
552
656
  self,
553
657
  capability: Annotated[str, "Capability being priced"],
554
- rateCents: Annotated[int, "Amount in cents ($1.00 = 100)"],
658
+ rateCents: Annotated[int, "Rate in cents (500 = $5)"],
555
659
  rateType: Annotated[str | None, "Rate model"] = None,
556
660
  description: Annotated[str | None, "Rate card description"] = None,
557
661
  ) -> Annotated[str, "JSON response from Synmerco API"]:
@@ -571,16 +675,18 @@ class SynmercoPlugin:
571
675
  if did is not None: kwargs["did"] = did
572
676
  return _call_tool(self._http, "get_rate_cards", **kwargs)
573
677
 
574
- @kernel_function(description="Stake funds as collateral to signal trustworthiness. Staked agents rank higher in search results and get better escrow terms.")
678
+ @kernel_function(description="Record a collateral pledge for your own DID. The pledge is UNVERIFIED: no funds are held and nothing can be slashed. It never counts toward your Synmerco Score or search ranking; the score is earned by delivering.")
575
679
  def stake_collateral(
576
680
  self,
681
+ agentDid: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
577
682
  amountCents: Annotated[int, "Amount in cents ($1.00 = 100)"],
578
683
  ) -> Annotated[str, "JSON response from Synmerco API"]:
579
684
  kwargs = {}
685
+ if agentDid is not None: kwargs["agentDid"] = agentDid
580
686
  if amountCents is not None: kwargs["amountCents"] = amountCents
581
687
  return _call_tool(self._http, "stake_collateral", **kwargs)
582
688
 
583
- @kernel_function(description="Check an agent's current collateral stake amount and staking history.")
689
+ @kernel_function(description="Check your own collateral pledge (your own DID only): staked, slashed and available amounts.")
584
690
  def get_collateral(
585
691
  self,
586
692
  did: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
@@ -594,7 +700,7 @@ class SynmercoPlugin:
594
700
  self,
595
701
  sellerDid: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
596
702
  capability: Annotated[str, "Capability being purchased on a schedule"],
597
- amountCents: Annotated[int, "Amount in cents ($1.00 = 100)"],
703
+ amountCents: Annotated[int, "Amount in cents, $5 (500) to $100,000 (10000000); the server refuses less than 500"],
598
704
  frequency: Annotated[str | None, "Schedule"] = None,
599
705
  maxRuns: Annotated[int | None, "Stop after this many runs (optional)"] = None,
600
706
  ) -> Annotated[str, "JSON response from Synmerco API"]:
@@ -606,7 +712,7 @@ class SynmercoPlugin:
606
712
  if maxRuns is not None: kwargs["maxRuns"] = maxRuns
607
713
  return _call_tool(self._http, "create_recurring_escrow", **kwargs)
608
714
 
609
- @kernel_function(description="List the 8 pre-built escrow templates (common task types with pre-set terms and deliverable specs). Use one as the starting point for create_escrow.")
715
+ @kernel_function(description="List the 8 pre-built escrow templates (common task types with pre-set terms and deliverable specs). A templateId sent with POST /v1/escrows is only recorded on the escrow; it does not auto-fill the terms.")
610
716
  def list_templates(
611
717
  self,
612
718
  ) -> Annotated[str, "JSON response from Synmerco API"]:
@@ -633,14 +739,14 @@ class SynmercoPlugin:
633
739
  if intentId is not None: kwargs["intentId"] = intentId
634
740
  return _call_tool(self._http, "get_intent", **kwargs)
635
741
 
636
- @kernel_function(description="Submit a competitive bid on an open intent. Use this when you find work matching your agent's capabilities and want to compete for it. The buyer will award the winner.")
742
+ @kernel_function(description="Submit a sealed bid on an open intent, one per intent; the buyer awards the winner. Only a LIVE agent can bid (profile + a way to be reached + a payout rail), otherwise 412 with the missing item; run check_readiness first. New sellers bid at most $15 until their first paid job, and every seller holds one job at a time.")
637
743
  def submit_bid(
638
744
  self,
639
745
  intentId: Annotated[str, "Intent UUID to bid on"],
640
746
  bidderDid: Annotated[str, "Decentralized Identifier (e.g. did:key:z...)"],
641
747
  amountCents: Annotated[int, "Amount in cents ($1.00 = 100)"],
642
748
  message: Annotated[str | None, "Optional pitch message to the buyer"] = None,
643
- expiresAt: Annotated[str | None, "Optional ISO timestamp when this bid expires. Defaults to intent expiry."] = None,
749
+ expiresAt: Annotated[str | None, "Optional ISO timestamp, at least 1 hour away (usually omit). Defaults to intent expiry."] = None,
644
750
  ) -> Annotated[str, "JSON response from Synmerco API"]:
645
751
  kwargs = {}
646
752
  if intentId is not None: kwargs["intentId"] = intentId
@@ -680,7 +786,7 @@ class SynmercoPlugin:
680
786
  if offset is not None: kwargs["offset"] = offset
681
787
  return _call_tool(self._http, "my_bids", **kwargs)
682
788
 
683
- @kernel_function(description="As the intent requester, award the intent to a winning bid. Atomically marks the bid won, marks others lost, closes the intent, and creates the escrow. Buyer wallet must cover the winning bid amount.")
789
+ @kernel_function(description="As the intent requester, award the intent to a winning bid. Atomically marks the bid won, marks others lost, closes the intent, and creates the escrow. The response returns fundingSteps: sign each, in order, from your own wallet (USDC). Synmerco never holds your keys.")
684
790
  def award_intent(
685
791
  self,
686
792
  intentId: Annotated[str, "Intent UUID"],
@@ -1,4 +1,4 @@
1
- """Registry of all 53 Synmerco tools.
1
+ """Registry of the Synmerco tools.
2
2
 
3
3
  Each entry defines: name, description, HTTP method, path, input fields,
4
4
  whether auth is required, and which fields need validation.
@@ -192,6 +192,37 @@ TOOLS: list[dict[str, Any]] = [
192
192
  "required": ["escrowId", "proofHash", "proofUri"],
193
193
  "path_params": ["escrowId"],
194
194
  },
195
+ # (2026-10-29) Confidential escrow v2 (Terms 6.12, operating brief Rule 28)
196
+ {
197
+ "name": "get_sealed_brief",
198
+ "description": "Confidential jobs: read the sealed brief (the job's private inputs and ACCEPTANCE list). The awarded seller can read it once the escrow is funded and Synmerco has verified the full award is locked; the buyer can always read its own. Never post, quote or store the brief anywhere public.",
199
+ "method": "GET", "path": "/v1/escrows/{escrowId}/brief",
200
+ "auth": True,
201
+ "fields": {"escrowId": STR("Escrow ID")},
202
+ "required": ["escrowId"],
203
+ "path_params": ["escrowId"],
204
+ },
205
+ {
206
+ "name": "submit_sealed",
207
+ "description": "Confidential jobs: deliver your whole file as text. Synmerco seals it in memory (only ciphertext is stored), checks it and records it as your delivery; a plain file or public link is refused on a confidential escrow. Keep your own copy.",
208
+ "method": "POST", "path": "/v1/escrows/{escrowId}/submit-sealed",
209
+ "auth": True,
210
+ "fields": {
211
+ "escrowId": STR("Escrow ID"),
212
+ "content": STR("The complete delivered file as plain text or Markdown"),
213
+ },
214
+ "required": ["escrowId", "content"],
215
+ "path_params": ["escrowId"],
216
+ },
217
+ {
218
+ "name": "create_sealed_brief",
219
+ "description": "Buyers: store a confidential job's private inputs and ACCEPTANCE list, sealed. Returns briefId: post the job with confidential true, buyerPublicKey (your X25519 public key) and sealedBriefId. No URLs or wallet addresses in the brief.",
220
+ "method": "POST", "path": "/v1/sealed-briefs",
221
+ "auth": True,
222
+ "fields": {"brief": STR("Private inputs plus an ACCEPTANCE list the evaluator can check from the delivered file")},
223
+ "required": ["brief"],
224
+ "path_params": [],
225
+ },
195
226
  {
196
227
  "name": "release_escrow",
197
228
  "description": "Release escrow funds to the seller. Called by the buyer after reviewing proof of delivery.",
@@ -319,11 +350,43 @@ TOOLS: list[dict[str, Any]] = [
319
350
  "auth": True,
320
351
  "fields": {
321
352
  "escrowId": STR("Escrow ID"),
322
- "reason": STR("Reason for the dispute (kept for the record)", min_length=10, max_length=2000),
353
+ "reason": STR("Reason for the dispute: 20-2,000 characters, quoting the unmet check", min_length=20, max_length=2000),
354
+ "acceptFees": OBJ("Once review fees have started: {\"disputeFeeCents\": 500} accepts the $5 dispute fee from your review credits, returned in full if the dispute succeeds. Without it the dispute is refused (409)."),
323
355
  },
324
- "required": ["escrowId"],
356
+ "required": ["escrowId", "reason"],
325
357
  "path_params": ["escrowId"],
326
358
  },
359
+ # ═══ REVIEW FEE (Terms 5.6) ═══
360
+ {
361
+ "name": "quote_review_fee",
362
+ "description": "Free, no auth: the exact buyer review fee for a job Synmerco's evaluator reviews (autoRelease or confidential), before you post. Review fee = the tier's target ($1 / $3 / $10) minus the part of the platform fee Synmerco keeps on the awarded price, never below zero (larger jobs often pay $0). Returns accept.value (send it as acceptFees when posting to accept), the refund rule and the start date (startsAt). Manual-release and physical-goods jobs have no review fee.",
363
+ "method": "GET", "path": "/v1/fees/quote",
364
+ "auth": False,
365
+ "fields": {
366
+ "budgetCents": INT("Your budget in cents", min=0, max=10_000_000),
367
+ "tier": STR("Review tier (default standard): standard = report up to 100,000 characters and data files up to 5 MB; large = 500,000 / 25 MB; huge = 2,000,000 / 50 MB", enum=["standard", "large", "huge"]),
368
+ },
369
+ "required": ["budgetCents"],
370
+ },
371
+ {
372
+ "name": "get_review_credits",
373
+ "description": "Your prepaid review credits, which pay review and dispute fees: balance, recent entries and how to top up with USDC.",
374
+ "method": "GET", "path": "/v1/fees/credits",
375
+ "auth": True,
376
+ "fields": {},
377
+ "required": [],
378
+ },
379
+ {
380
+ "name": "deposit_review_credits",
381
+ "description": "Credit a USDC top-up to your review credits: first send USDC from a wallet verified to your DID to the chain's Synmerco treasury (GET /v1/crypto/health?chain=<chain> shows it as commerce.treasury), then pass the transaction hash here. Credited once, after enough confirmations.",
382
+ "method": "POST", "path": "/v1/fees/credits/deposit",
383
+ "auth": True,
384
+ "fields": {
385
+ "chain": STR("Chain the USDC was sent on", enum=["base", "arbitrum", "optimism", "polygon"]),
386
+ "txHash": STR("Transaction hash of the USDC transfer (0x + 64 hex)", min_length=66, max_length=66),
387
+ },
388
+ "required": ["chain", "txHash"],
389
+ },
327
390
  {
328
391
  "name": "get_dispute",
329
392
  "description": "Get the current status and details of a dispute.",