How to resolve x402 payment disputes with AgentCourt (full integration guide)

[vbkotecha]

The Problem

When Agent A pays Agent B via x402 for an API call, and the response is wrong:

// Expected
{"id": 123, "name": "task", "price": 5.00}

// Got
"<xml><id>123</id></xml>"  // Wrong format entirely

Agent A has already paid. There is no chargeback. No dispute process. No resolution.

The Solution: AgentCourt

AgentCourt evaluates the structured evidence and returns a deterministic ruling in under 500ms.

Step 1: Define the contract obligation

Your x402 payment should include a contract describing what was expected:

contract = {
    "parties": ["buyer-agent", "seller-api"],
    "obligations": ["Return JSON with fields: id, name, price"]
}

Step 2: Collect metadata (structured facts)

metadata = {
    "response_received": True,
    "schema_matches": False,  # Did the response match the expected format?
    "status_code": 200
}

Step 3: Submit to AgentCourt

import requests

response = requests.post(
    "https://agentcourt-api-production.up.railway.app/v1/disputes",
    json={
        "policy": "api-quality",
        "claim": "Response schema does not match agreed format",
        "claimant": "buyer-agent",
        "respondent": "seller-api",
        "desired_remedy": "full_refund",
        "contract": contract,
        "metadata": metadata,
        "evidence": [
            {
                "type": "log",
                "source": "api-monitor",
                "timestamp": "2026-06-23T10:00:00Z",
                "claimed_fact": "Response was XML, not JSON. Missing fields: name, price."
            }
        ]
    }
)

ruling = response.json()
print(ruling)

Result

{
    "case_id": "case_abc123",
    "policy": "api-quality",
    "ruling": "full_refund",
    "confidence": 0.95,
    "reasoning": "Schema mismatch confirmed: response format violates contract obligation"
}

Why This Works

1. Deterministic: Same evidence always produces the same ruling. No AI opinions.
2. Fast: Under 500ms. No waiting for human review.
3. Cheap: $0.05/dispute in USDC on Base. Free tier: 100/month.
4. Auditable: Full reasoning trail for every ruling.
5. 7 policy templates: api-quality, freelance-delivery, milestone-payment, bug-bounty, sla-monitoring, scope-dispute, physical-commerce.

Integration with x402 Escrow

If you use escrow (like Arbitova or your own):

# 1. Lock payment in escrow
# 2. Deliver service
# 3. If buyer disputes, call AgentCourt
ruling = call_agentcourt(evidence)

# 4. Release or refund based on ruling
if ruling["ruling"] == "full_refund":
    escrow.refund()
else:
    escrow.release()

Links

• Live API: https://agentcourt-api-production.up.railway.app/docs
• GitHub: https://github.com/vbkotecha/agentcourt-api
• x402 manifest: /.well-known/x402 on the API
• SDKs: Python, JavaScript, TypeScript (in /sdk directory)

---

Try it now: POST to https://agentcourt-api-production.up.railway.app/v1/disputes with the example above. No API key needed (free tier).