Developer Documentation

Overview

Clinch is a trustless USDC escrow platform on Arc Network. Our API lets you embed escrow deals, AI dispute resolution, and automated fee collection directly into your product.

Key features:

• Peer-to-peer USDC escrow on Arc Testnet
• AI-powered dispute analysis via OpenRouter (DeepSeek → Llama → Gemini)
• x402 nanopayments — pay $0.001 per AI analysis
• Autonomous agent wallet — fees flow to your agent, not a middleman
• Real-time webhooks for deal state changes

Quickstart

Get an API key and make your first API call in under 2 minutes.

1. Register for an API key

curl -X POST https://clinch-one.vercel.app/api/dev/register \
  -H "Content-Type: application/json" \
  -d '{"name": "My App", "email": "dev@myapp.com"}'

Save the returned apiKey — you won't see it again.

2. Get platform metrics (no auth needed)

curl https://clinch-one.vercel.app/api/public/metrics

3. Create an escrow deal

curl -X POST https://clinch-one.vercel.app/api/external/deals \
  -H "X-API-Key: *** \
  -H "Content-Type: application/json" \
  -d '{"partyB": "0x...", "amountA": "100", "dealType": "OneSided", "title": "Freelance Payment"}'

Authentication

All API requests (except public endpoints and registration) require an API key passed via the X-API-Key header.

curl -H "X-API-Key: *** https://clinch-one.vercel.app/api/external/deals/1

You can also pass the key as a query parameter:

curl "https://clinch-one.vercel.app/api/external/deals/1?api_key=***

API Reference

Base URL: https://clinch-one.vercel.app

Public Endpoints

Developer Endpoints

External API (authenticated)

Agent Endpoints

Deals

A deal represents an escrow agreement between two parties. Deals can be MutualStake (both parties deposit) or OneSided (only the client deposits, the worker is paid on completion).

Deal lifecycle

When a deal is created, resolved, or disputed, all configured webhooks receive a real-time event. See the Webhooks section for payload schemas.

Disputes & AI Analysis

When deal parties disagree on the outcome, either party can raise a dispute. Clinch's AI assistant analyzes chat history, deal context, and vote data to recommend a fair settlement.

AI Analysis endpoint (x402 protected)

The POST /api/disputes/:id/ai-analysis endpoint requires a $0.001 USDC payment via the x402 protocol on Arc Testnet.

// The frontend SDK handles x402 payment automatically
// Manual curl equivalent requires x402 headers:
curl -X POST https://clinch-one.vercel.app/api/disputes/1/ai-analysis \
  -H "X-API-Key: *** \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: ..."    # Generated by x402 client

Webhooks

Webhooks notify your backend in real-time when deal states change. Register a URL and select which events to receive. Each payload is signed with an HMAC-SHA256 signature so you can verify authenticity.

Register a webhook

curl -X POST https://clinch-one.vercel.app/api/dev/webhooks \
  -H "X-API-Key: *** \
  -H "Content-Type: application/json" \
  -d '{"url": "https://myapp.com/webhooks/clinch", "events": ["deal.created", "deal.resolved", "dispute.raised"]}'

Verify a webhook signature

// Node.js example
const crypto = require("crypto");
const signature = req.headers["x-clinch-signature"];
const payload = JSON.stringify(req.body);
const expected = crypto
  .createHmac("sha256", WEBHOOK_SECRET)
  .update(payload)
  .digest("hex");
if (signature !== expected) throw new Error("Invalid signature");

Event payloads

deal.created

{
  "event": "deal.created",
  "timestamp": "2026-07-01T12:00:00Z",
  "data": {
    "onChainId": 42,
    "partyA": "0x...",
    "partyB": "0x...",
    "amountA": "100.00",
    "amountB": "0.00",
    "dealType": "OneSided"
  }
}

deal.resolved

{
  "event": "deal.resolved",
  "timestamp": "2026-07-01T12:30:00Z",
  "data": {
    "onChainId": 42,
    "winner": "PartyAWins",
    "winnerPayout": 99.75,
    "platformFee": 0.25
  }
}

dispute.raised

{
  "event": "dispute.raised",
  "timestamp": "2026-07-01T12:15:00Z",
  "data": {
    "onChainId": 42,
    "raisedBy": "0x...",
    "arbitrator": "0x..."
  }
}

Agent Wallet

The Clinch Agent is an autonomous AI entity with its own Circle Programmable Wallet on Arc Testnet. All platform fees (0.25% per deal, 2% for disputed deals) flow directly into the agent's wallet.

Agent capabilities

• Self-funding: The agent pays for its own AI compute via x402 nanopayments
• Auto-dispute handling: Detects stale deals and notifies admins
• x402 service: Registered on Circle Agent Marketplace — other agents can hire it via nanopayments
• Transparent: Wallet balance and activity visible on the dashboard

Get agent status

curl -H "Authorization: Bearer *** https://clinch-one.vercel.app/api/agent/wallet
curl -H "Authorization: Bearer *** https://clinch-one.vercel.app/api/agent/metrics

x402 service manifest

curl https://clinch-one.vercel.app/api/agent/manifest

SDK & Libraries

The @clinch/sdk JavaScript SDK wraps the Clinch API for Node.js and browser environments.

Installation

npm install @clinch/sdk

Usage

import Clinch from "@clinch/sdk";

const clinch = new Clinch({ apiKey: "*** });

// Get platform metrics
const metrics = await clinch.getMetrics();

// Create a deal
const deal = await clinch.createDeal({
  partyB: "0x...",
  amountA: "100",
  dealType: "OneSided",
  title: "Freelance Payment",
});

// Get AI dispute analysis
const analysis = await clinch.getDisputeAnalysis(deal.onChainId);
console.log(analysis.recommendedOutcome); // "PartyAWins"

// Get agent wallet balance
const agent = await clinch.getAgentWallet();
console.log(agent.balance); // "0.25"

Examples

Automated freelancer escrow

A platform that connects freelancers with clients can use Clinch to hold payments in escrow. When the work is delivered and both parties agree, funds are released. If disputed, the AI arbitrator analyzes chat history and recommends a settlement.

Agent-to-agent arbitration

Two AI agents on Arc can agree to use Clinch as their dispute resolver. Each agent callsPOST /api/external/deals/:id/analysis via x402 — paying $0.001 USDC from their own wallets for the AI analysis.

Supply chain milestone payments

Use OneSided escrows for milestone-based payments. The client deposits the full amount, and each milestone completion triggers a partial release. The agent wallet collects the platform fee on each release.