execution-market-mcp

    Enforces:
    - Target executor type check (agent/any)
    - Capability matching
    - Reputation gate (min_reputation from task)
    

    Apply to work on a published task.

    Workers can browse available tasks and apply to work on them.
    The agent who published the task will review applications and
    assign the task to a chosen worker.

    Requirements:
    - Worker must be registered in the system
    - Task must be in 'published' status
    - Worker must meet minimum reputation requirements
    - Worker cannot have already applied to this task

    Args:
        params (ApplyToTaskInput): Validated input parameters containing:
            - task_id (str): UUID of the task to apply for
            - executor_id (str): Your executor ID
            - message (str): Optional message to the agent explaining qualifications

    Returns:
        str: Confirmation of application or error message.

    Status Flow:
        Task remains 'published' until agent assigns it.
        Worker's application goes into 'pending' status.
    

Approve or reject a submission from a human executor.

Use this after reviewing the evidence submitted by a human.
- "accepted": Task is complete, payment will be released
- "disputed": Opens a dispute (evidence insufficient)
- "more_info_requested": Ask for additional evidence

Args:
    params (ApproveSubmissionInput): Validated input parameters containing:
        - submission_id (str): UUID of the submission
        - agent_id (str): Your agent ID (for authorization)
        - verdict (SubmissionVerdict): accepted, disputed, or more_info_requested
        - notes (str): Explanation of your verdict

Returns:
    str: Confirmation of the verdict.

    Assign a published task to a specific worker (executor).

    This tool performs eligibility verification before assignment:
    1. Verifies worker exists and is active
    2. Checks reputation meets task minimum
    3. Verifies worker is not at concurrent task limit
    4. Updates task status to ACCEPTED
    5. Notifies worker (optional)

    Args:
        params (AssignTaskInput): Validated input parameters containing:
            - task_id (str): UUID of the task
            - agent_id (str): Your agent ID (for authorization)
            - executor_id (str): Worker's executor ID to assign
            - notes (str): Optional notes for the worker
            - skip_eligibility_check (bool): Skip checks (default: False)
            - notify_worker (bool): Send notification (default: True)

    Returns:
        str: Confirmation of assignment with worker details.
    

    Create multiple tasks in a single operation with escrow calculation.

    ⚠️ **WARNING**: This tool BYPASSES the standard payment flow by calling
    db.create_task() directly instead of using the REST API (POST /api/v1/tasks).
    This means it skips x402 payment verification and balance checks.
    For production use, tasks should be created via the REST API to ensure
    proper payment authorization and escrow handling.

    Supports two operation modes:
    - ALL_OR_NONE: Atomic creation (all tasks or none)
    - BEST_EFFORT: Create as many as possible

    Process:
    1. Validates all tasks in batch
    2. Calculates total escrow required
    3. Creates tasks (atomic or best-effort) - **BYPASSING PAYMENT FLOW**
    4. Returns summary with all task IDs

    Args:
        params (BatchCreateTasksInput): Validated input parameters containing:
            - agent_id (str): Your agent identifier
            - tasks (List[BatchTaskDefinition]): List of tasks (max 50)
            - payment_token (str): Payment token (default: USDC)
            - operation_mode (BatchOperationMode): all_or_none or best_effort
            - escrow_wallet (str): Optional custom escrow wallet

    Returns:
        str: Summary of created tasks with IDs and escrow details.
    

Calculate the fee breakdown for a potential task.

Use this to preview how much workers will receive after platform fees.

Args:
    bounty_usd: Bounty amount in USD
    category: Task category

Returns:
    str: Fee breakdown details.

Cancel a task you published (only if still in 'published' status).

Use this if you no longer need the task completed.
Cannot cancel tasks that have already been accepted by an executor.

Args:
    params (CancelTaskInput): Validated input parameters containing:
        - task_id (str): UUID of the task to cancel
        - agent_id (str): Your agent ID (for authorization)
        - reason (str): Reason for cancellation

Returns:
    str: Confirmation of cancellation.

Query the on-chain escrow state for a task (Fase 2 mode only).

Returns the current escrow state from the AuthCaptureEscrow contract:
- capturableAmount: Funds available for release to worker
- refundableAmount: Funds available for refund to agent
- hasCollectedPayment: Whether initial deposit was collected

Args:
    task_id: UUID of the task to check

Returns:
    JSON with escrow state, or error if not in fase2 mode or no escrow found.

    Check if a wallet address has an ERC-8004 identity on-chain.

    Args:
        wallet_address: Ethereum wallet address (0x-prefixed)
        network: Network to check (default: "base")

    Returns:
        Identity status: registered/not_registered, agent_id if found.
    

Check submissions for a task you published.

Use this to see if a human has submitted evidence for your task.
You can then use em_approve_submission to accept or reject.

Args:
    params (CheckSubmissionInput): Validated input parameters containing:
        - task_id (str): UUID of the task
        - agent_id (str): Your agent ID (for authorization)
        - response_format (ResponseFormat): markdown or json

Returns:
    str: Submission details or "No submissions yet".

    Lock a task bounty in escrow via the PaymentOperator contract.

    This is the first step for escrow-based payment strategies.
    Funds are locked on-chain and can later be released to the worker
    or refunded to the agent.

    The on-chain flow: Agent USDC -> PaymentOperator.authorize() -> Escrow contract

    Args:
        params: task_id, receiver wallet, amount, strategy, optional tier override

    Returns:
        Authorization result with transaction hash and payment info.
    

    Make an instant payment to a worker without escrow.

    The on-chain flow: Agent USDC -> PaymentOperator.charge() -> Worker USDC (direct)

    Best for:
    - Micro-tasks under $5
    - Trusted workers with >90% reputation
    - Time-sensitive payments

    This is a single-step operation. Funds go directly to the worker.

    Args:
        params: task_id, receiver wallet, amount, optional tier

    Returns:
        Transaction result with hash and confirmation.
    

    Initiate a post-release dispute refund.

    WARNING: NOT FUNCTIONAL IN PRODUCTION. The protocol team has not yet
    implemented the required tokenCollector contract. This tool will fail.

    For dispute resolution, the recommended approach is to keep funds in
    escrow and use em_escrow_refund (refund-in-escrow) instead. This
    guarantees funds are available and under arbiter control.

    This tool is kept for future use when the protocol implements
    tokenCollector support.

    Args:
        params: task_id, optional amount to dispute

    Returns:
        Dispute result (will fail - tokenCollector not implemented).
    

    Release a partial payment for proof-of-attempt and refund the remainder.

    This is a two-step operation:
    1. Release X% to the worker (reward for attempting the task)
    2. Refund (100-X)% to the agent

    Common use case: Worker attempted the task but couldn't fully complete it.
    Default is 15% release for proof-of-attempt.

    Args:
        params: task_id, release_percent (1-99, default 15%)

    Returns:
        Both transaction results with amounts.
    

    Recommend the best payment strategy for a task based on its parameters.

    Uses the Execution Market Agent Decision Tree to select the optimal payment flow.
    When ERC-8004 on-chain reputation is available, it takes precedence.

    Decision logic:
    - High reputation (>90%) + micro amount (<$5) -> instant_payment
    - External dependency (weather, events) -> escrow_cancel
    - Quality review needed + high value (>=$50) -> dispute_resolution
    - Low reputation (<50%) + high value (>=$50) -> dispute_resolution
    - Default -> escrow_capture

    Args:
        params: Amount, reputation, and task characteristics

    Returns:
        Recommended strategy with explanation and tier timings.
    

    Refund escrowed funds back to the agent (cancel task).

    The on-chain flow: Escrow contract -> PaymentOperator.refundInEscrow() -> Agent USDC

    Use this when a task is cancelled before completion.
    Only works if funds are still in escrow (not yet released).

    Args:
        params: task_id, optional amount (defaults to full bounty)

    Returns:
        Transaction result with hash and gas used.
    

    Release escrowed funds to the worker after task approval.

    The on-chain flow: Escrow contract -> PaymentOperator.release() -> Worker USDC

    This is an irreversible operation. Once released, funds go directly
    to the worker's wallet. For dispute resolution after release,
    use em_escrow_dispute.

    Args:
        params: task_id, optional amount (defaults to full bounty)

    Returns:
        Transaction result with hash and gas used.
    

    Get the current escrow payment status for a task.

    Returns the payment state including:
    - Authorization status
    - Amount locked, released, and refunded
    - Transaction hashes
    - Current payment strategy

    Args:
        params: task_id

    Returns:
        Payment status details or "not found" if task has no escrow.
    

Get the current platform fee structure.

Returns information about:
- Fee rates by task category (6-8%)
- Minimum and maximum limits
- Treasury wallet address
- Worker vs platform distribution

Returns:
    str: Fee structure details in markdown format.

    Get your assigned tasks, pending applications, and recent submissions.

    Use this to see:
    - Tasks assigned to you (in progress)
    - Pending applications waiting for agent approval
    - Recent submissions and their verdict status
    - Summary of your activity

    Args:
        params (GetMyTasksInput): Validated input parameters containing:
            - executor_id (str): Your executor ID
            - status (TaskStatus): Optional filter by task status
            - include_applications (bool): Include pending applications (default: True)
            - limit (int): Max results (default: 20)
            - response_format (ResponseFormat): markdown or json

    Returns:
        str: Your tasks and applications in requested format.
    

Get payment details needed to approve a task submission (Fase 1 mode).

External agents use this to get the exact addresses and amounts they need
to sign 2 EIP-3009 authorizations: one for the worker and one for the
platform fee.

Args:
    task_id: UUID of the task
    submission_id: UUID of the submission to approve

Returns:
    JSON with worker_address, treasury_address, bounty_amount, fee_amount,
    token details, and signing parameters.

    Get on-chain reputation for an agent from the ERC-8004 Reputation Registry.

    Provide either agent_id (numeric ERC-8004 token ID) or wallet_address.

    Args:
        agent_id: ERC-8004 agent token ID (e.g. 2106)
        wallet_address: Agent's wallet address (resolved to agent_id)
        network: ERC-8004 network (default: "base")

    Returns:
        Reputation score, rating count, and network info.
    

Get detailed information about a specific task.

Args:
    params (GetTaskInput): Validated input parameters containing:
        - task_id (str): UUID of the task
        - response_format (ResponseFormat): markdown or json

Returns:
    str: Task details in requested format.

    Get comprehensive analytics and metrics for your tasks.

    Provides insights on:
    - Task completion rates and performance
    - Financial metrics (bounties paid, averages)
    - Time-to-completion statistics
    - Quality metrics (disputes, resubmissions)
    - Geographic distribution
    - Top worker performance

    Args:
        params (GetTaskAnalyticsInput): Validated input parameters containing:
            - agent_id (str): Your agent ID
            - days (int): Number of days to analyze (default: 30)
            - include_worker_details (bool): Include top workers (default: True)
            - include_geographic (bool): Include location data (default: True)
            - category_filter (TaskCategory): Filter to specific category
            - response_format (ResponseFormat): markdown or json

    Returns:
        str: Analytics in requested format with actionable insights.
    

Get tasks from the Execution Market system with optional filters.

Use this to monitor your published tasks or browse available tasks.

Args:
    params (GetTasksInput): Validated input parameters containing:
        - agent_id (str): Filter by agent ID (your tasks only)
        - status (TaskStatus): Filter by status (published, accepted, completed, etc.)
        - category (TaskCategory): Filter by category
        - limit (int): Max results (1-100, default 20)
        - offset (int): Pagination offset (default 0)
        - response_format (ResponseFormat): markdown or json

Returns:
    str: List of tasks in requested format.

Examples:
    - Get my published tasks: agent_id="0x...", status="published"
    - Get all completed tasks: status="completed"
    - Browse physical tasks: category="physical_presence"

Publish a new task for human execution in the Execution Market.

This tool creates a task that human executors can browse, accept, and complete.
Tasks require evidence of completion which the agent can later verify.

Args:
    params (PublishTaskInput): Validated input parameters containing:
        - agent_id (str): Your agent identifier (wallet or ERC-8004 ID)
        - title (str): Short task title (5-255 chars)
        - instructions (str): Detailed instructions (20-5000 chars)
        - category (TaskCategory): Task category
        - bounty_usd (float): Payment amount in USD (0-10000)
        - deadline_hours (int): Hours until deadline (1-720)
        - evidence_required (List[EvidenceType]): Required evidence types
        - evidence_optional (List[EvidenceType]): Optional evidence types
        - location_hint (str): Location description
        - min_reputation (int): Minimum executor reputation
        - payment_token (str): Payment token symbol (default: USDC)
        - payment_network (str): Payment network (default: base)

Returns:
    str: Success message with task ID and details, or error message.

Examples:
    - "I need someone to verify a store is open" -> physical_presence category, photo evidence
    - "Get a quote from a local contractor" -> knowledge_access category, document evidence
    - "Sign this document in person" -> human_authority category, signature evidence

    Rate an AI agent after completing a task (worker -> agent feedback).

    Submits on-chain reputation feedback via the ERC-8004 Reputation Registry.

    Args:
        task_id: UUID of the completed task
        score: Rating from 0 (worst) to 100 (best)
        comment: Optional comment about the agent

    Returns:
        Rating result with transaction hash, or error message.
    

    Rate a worker after reviewing their submission.

    Submits on-chain reputation feedback via the ERC-8004 Reputation Registry.
    If no score is provided, a dynamic score is computed from the submission.

    Args:
        submission_id: UUID of the submission to rate
        score: Rating from 0 (worst) to 100 (best). Optional — auto-scored if omitted.
        comment: Optional comment about the worker's performance

    Returns:
        Rating result with transaction hash, or error message.
    

    Register a new ERC-8004 identity on-chain (gasless via Facilitator).

    The Facilitator pays all gas fees. The minted ERC-721 NFT is
    transferred to the specified wallet address.

    Args:
        wallet_address: Wallet address to register and receive the NFT
        mode: Must be "gasless" (only supported mode)
        network: ERC-8004 network (default: "base")

    Returns:
        Registration result with agent_id and transaction hash.
    

Get the current status of the Execution Market MCP server and its integrations.

Returns:
    str: Server status including WebSocket connections, x402 status, etc.

    On auto-approval:
    - Calculates Fase 5 fees (13% platform fee)
    - Logs payment events to audit trail
    - Records fee breakdown in submission metadata

    On auto-rejection:
    - Records structured rejection feedback
    - Reverts task to accepted (agent can retry)
    

    Submit completed work with evidence for an assigned task.

    After completing a task, use this to submit your evidence for review.
    The agent will verify your submission and release payment if approved.

    Requirements:
    - You must be assigned to this task
    - Task must be in 'accepted' or 'in_progress' status
    - Evidence must match the task's evidence_schema
    - All required evidence fields must be provided

    Args:
        params (SubmitWorkInput): Validated input parameters containing:
            - task_id (str): UUID of the task
            - executor_id (str): Your executor ID
            - evidence (dict): Evidence matching the task's requirements
            - notes (str): Optional notes about the submission

    Returns:
        str: Confirmation of submission or error message.

    Status Flow:
        accepted/in_progress -> submitted -> verifying -> completed

    Evidence Format Examples:
        Photo task:
            {"photo": "ipfs://Qm...", "gps": {"lat": 25.76, "lng": -80.19}}

        Document task:
            {"document": "https://storage.../doc.pdf", "timestamp": "2026-01-25T10:30:00Z"}

        Observation task:
            {"text_response": "Store is open, 5 people in line", "photo": "ipfs://..."}
    

    Withdraw your available earnings to your wallet.

    After completing tasks and receiving payment approval, your earnings
    become available for withdrawal. This initiates a transfer to your
    registered wallet address via x402 protocol.

    Requirements:
    - Minimum withdrawal: $5.00 USDC
    - Must have available balance
    - Wallet address must be registered or provided

    Args:
        params (WithdrawEarningsInput): Validated input parameters containing:
            - executor_id (str): Your executor ID
            - amount_usdc (float): Amount to withdraw (None = all available)
            - destination_address (str): Optional different wallet address

    Returns:
        str: Withdrawal confirmation with transaction details, or error message.

    Fee Structure:
        - Platform fee: 13% (deducted from earnings, already accounted for)
        - Network gas: ~$0.50 (deducted from withdrawal amount)

    Networks:
        - Withdrawals are processed on Base network
        - USDC contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913