# settle · skill

Programmable escrow for agent work. Commit funds upfront. Verify a condition. Authorize payout. Mark settled only after payout confirmation.

API base: https://settle.ronakdaya.com

## The settlement calls

### 1. create_escrow
`POST /escrow/create` returns a contract in `pending_funding`. The response includes one-time `claim_token` for provider payout registration. Manual conditions also return one-time `confirmation_token`; store it as a bearer secret.

Optional x402 deferred path: `POST /x402/deferred/offer` returns a deferred offer and signing payload. `POST /x402/deferred/commit` verifies the agent signature and creates or links the escrow. The commitment does not bypass funding or condition verification.

### 2. fund_escrow
Primary funding is USDC on Base or USDG on X Layer. x402/MPP exposes the rail surface. Stripe Checkout and Stripe Link SPT are sandbox on-ramp tests until live Stripe is activated.

Base agents: use Base MCP/Base Account for wallet control and USDC on Base. Use x402 for pay-to-access. Use Settle when funds should wait for a condition before final settlement.

### 3. verify_condition
`POST /escrow/{id}/verify` or a trusted webhook checks the condition. Deterministic conditions auto-authorize payout when provider-claimed payout details are registered. Verifier request bodies cannot set payout destinations. Manual conditions stop at `condition_met`.

### 4. release_status
`GET /escrow/{id}`, `GET /escrow/{id}/status`, or `GET /escrow/{id}/payout` returns the current state.

### 5. authorize_release
`POST /escrow/{id}/authorize-release` moves `condition_met` to `settlement_pending` when auto-authorization is unavailable or not desired. Payout details must be registered through `/claim` first, or this request must include the create-time `claim_token` with `payout_method` and `payout_destination`. With `payout_method: "base_usdc"` or `"xlayer_usdg"`, it signs and broadcasts an ERC-20 payout from the configured operator vault.

### 6. confirm_payout
`GET /escrow/{id}/payout?sync=1` confirms processor settlement from receipts. Manual rails should use signed `POST /webhooks/payout`. Unsigned `POST /escrow/{id}/payout` confirmation is debug-only. For Base USDC and X Layer USDG vault payouts, receipt sync settles only after status `0x1`.

A trusted payout processor can also call `POST /webhooks/payout` with a signed confirmation or failure notification. That is the deterministic settlement path for Link/Stripe-style payout verification.

## States

- `pending_funding`: created, awaiting funds.
- `held`: funded, awaiting condition.
- `condition_met`: condition passed, payout not yet authorized or missing payout details.
- `settlement_pending`: release authorized, payout pending confirmation.
- `settled`: payout confirmed to provider.
- `payout_failed`: payout attempt failed; retry authorization or refund.
- `refunded`: funds returned to client.
- `expired`: deadline expired before funding.
- `disputed`: awaiting human review.

Terminal states: `settled`, `refunded`, `expired`, `disputed`.

## Funding rails

- Stablecoin escrow: USDC on Base and USDG on X Layer are the primary v0.1 rails.
- Base-agent wallet: fund with USDC on Base from a Base Account or Base MCP-controlled wallet, then let Settle verify the condition before payout finalizes.
- Human card sandbox: `POST /escrow/{id}/checkout` redirects to hosted Stripe Checkout.
- Stripe Link sandbox: `POST /escrow/{id}/pay` or `POST /escrow/{id}/fund-spt` with a shared payment token.
- URL-pay wallet (x402): `POST /escrow/{id}/pay` returns an x402 challenge. Accepts usdc/base and usdg/xlayer.
- WalletConnect wallet: `GET /escrow/{id}/walletconnect?rail=base_usdc` returns an `eth_sendTransaction` intent for any WalletConnect-compatible EVM wallet. Use `rail=xlayer_usdg` for X Layer USDG when the connected wallet supports `eip155:196`. After broadcast, call `POST /escrow/{id}/sync-funding` with the tx hash.
- MPP-compatible agent: `POST /escrow/{id}/pay` can discover rails or submit a sandbox Link SPT credential.
- APP-style agent commerce: quote/escrow/verify/settle maps to the same contract lifecycle. OKX APP-specific message formats are planned once the escrow spec is public and stable.
- Direct stablecoin: `/fund-usdc-base` and `/fund-usdg-xlayer` return per-contract EVM deposit addresses. No memo is used. If a webhook misses a valid transfer, `POST /escrow/{id}/sync-funding` can verify a transaction receipt and move the contract to `held`.

## Payout rails

- Manual confirmation: `POST /escrow/{id}/payout` with a confirmation id.
- Base USDC: claim or authorize with `payout_method: "base_usdc"`, `claim_token`, and a 0x payout address, then sync with `GET /escrow/{id}/payout?sync=1`.
- X Layer USDG: claim or authorize with `payout_method: "xlayer_usdg"`, `claim_token`, and a 0x payout address, then sync with `GET /escrow/{id}/payout?sync=1`.
- Ethereum stablecoin: optional legacy rail via `payout_method: "usdc_ethereum"` or `"usdg_ethereum"`.
- Bridge: planned/off by default in v0.1. The API shape exists behind `payout_method: "bridge"` only when operator Bridge credentials are configured.

## Conditions

- `api_response`: endpoint returns expected status/body.
- `github_pr_merged`: PR is merged.
- `file_delivered`: URL returns 200 and optional sha256 matches.
- `manual`: client confirmation posts `{ "confirmed": true, "confirmation_token": "..." }` or sends `X-Settle-Confirmation-Token`.

## Minimal example

For retries, send `Idempotency-Key` on `POST /escrow/create` and `POST /x402/deferred/commit`. Public mutating endpoints may return `429` with `Retry-After`.

```bash
curl -X POST https://settle.ronakdaya.com/escrow/create \
  -H "content-type: application/json" \
  -d '{"amount_usdg":10,"gas_tip_percent":0,"client_wallet":"client","provider_wallet":"provider","condition":{"type":"manual","params":{},"deadline":"2026-12-31T17:00:00Z","fallback":"return_to_client"}}'
```

Expected deterministic settlement path with registered payout details: `pending_funding → held → condition_met → settlement_pending → settled`.

## Recipes

- PR bounty: create `github_pr_merged`, fund, register provider payout details, then verify after merge.
- Base agent task: use a Base MCP wallet to fund USDC on Base, register the provider payout address, and let `api_response`, `github_pr_merged`, or `file_delivered` auto-authorize payout when the condition passes.
- API job: create `api_response` with `url`, `expected_status`, and optional `expected_body`; deterministic verification can auto-authorize payout.
- File delivery: create `file_delivered` with `url` and optional `sha256`; fund with USDC on Base or USDG on X Layer.

Discovery: `/agent`, `/.well-known/mpp.json`, `/.well-known/agent-catalog.json`, `/.well-known/ai-tool/settle.json`, `/openapi.json`, `/llms.txt`, `/agents.txt`, `/examples`.
Contact: hi@ronakdaya.com