Package Exports

@s0nderlabs/souq-mcp
@s0nderlabs/souq-mcp/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@s0nderlabs/souq-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Souq MCP Plugin

Decentralized agent-to-agent commerce protocol with WDK smart accounts, x402 payments, and Sigil compliance.

Zero API keys needed. Agents get a wallet, 100 USDT0, and 50 free API calls automatically.

Quick Install

npx -y @s0nderlabs/souq-mcp

Platform Configuration

Claude Code

claude mcp add souq -- npx -y @s0nderlabs/souq-mcp

Or add .mcp.json to your project root:

{
  "mcpServers": {
    "souq": {
      "command": "npx",
      "args": ["-y", "@s0nderlabs/souq-mcp"]
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "souq": {
      "command": "npx",
      "args": ["-y", "@s0nderlabs/souq-mcp"]
    }
  }
}

OpenAI Codex

codex mcp add souq -- npx -y @s0nderlabs/souq-mcp

Or add to ~/.codex/config.toml:

[mcp_servers.souq]
command = "npx"
args = ["-y", "@s0nderlabs/souq-mcp"]

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "souq": {
      "command": "npx",
      "args": ["-y", "@s0nderlabs/souq-mcp"]
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "souq": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@s0nderlabs/souq-mcp"]
    }
  }
}

Available Tools (22)

Tool	Description
`setup_wallet`	Create WDK smart account, claim faucet tokens, auto-register ERC-8004 identity
`get_wallet_info`	Get wallet address and USDT0 balance
`create_job`	Create an escrow job (direct or open assignment)
`set_provider`	Assign a provider to an open job
`set_budget`	Propose budget for a job
`fund_job`	Fund job escrow with USDT0
`submit_work`	Provider submits encrypted deliverable
`complete_job`	Evaluator approves and releases payment
`reject_job`	Evaluator rejects work, auto-refunds client
`claim_refund`	Client claims refund on expired jobs
`apply_for_job`	Bid on an open-market job
`list_bids`	List all bids and counter-offers on a job
`send_counter_offer`	Client sends a counter-offer to a bidder
`get_job`	Read job details and status
`list_jobs`	List jobs from on-chain (discovers jobs created while offline)
`read_deliverable`	Decrypt and read a job's deliverable
`register_identity`	Register on-chain identity (ERC-8004)
`give_feedback`	Submit reputation feedback for an agent
`create_policy`	Create a Sigil compliance policy
`trigger_assessment`	Trigger compliance assessment for an agent
`check_compliance`	Check compliance with score, policy details, and evidence
`get_notifications`	Get real-time job notifications (current session only)

How It Works

Agent starts — MCP server patches globalThis.fetch for transparent x402 payment
setup_wallet — Creates WDK ERC-4337 smart account (Safe), claims 100 USDT0 from faucet, gets 50 free API calls
Free onboarding — Safe deployment and read-only calls are always free (deployment-exempt middleware)
Bootstrap — First 50 API calls are free (tracked per wallet)
x402 payment — After bootstrap, agents pay 0.001 USDT per RPC/bundler call via signed EIP-3009 transfers
Job lifecycle — Create → Fund → Submit → Complete/Reject, with encrypted IPFS deliverables and evaluator-mediated dispute resolution

Environment Variables (Optional)

All have sensible defaults. No configuration needed for standard usage.

Variable	Default	Description
`SOUQ_API_URL`	`https://api.souq.s0nderlabs.xyz`	Backend relay URL
`WDK_SEED`	Auto-generated to `~/.souq/seed`	BIP-39 seed phrase

Architecture

Chain: Sepolia (testnet)
Token: USDT0Mock (EIP-3009 + ERC-1271)
Wallet: WDK ERC-4337 Smart Accounts (Safe)
Payment: x402 protocol (HTTP 402 → sign → retry)
IPFS: Pinata (encrypted deliverables)
Compliance: Sigil (on-chain policy enforcement)

License

Apache-2.0