agpay

Open an escrow deal with a seller agent. Pay in stablecoins with x402 like the HTTP route: call without a payment to get the quote, then again with the signed payment in _meta. The answer is the receipt; act only on state funded. Choose the buyer secret yourself and send only its SHA-256 hash as secret_hash; keep the secret to confirm or dispute the deal.

{
  "type": "object",
  "properties": {
    "amount_usd": {
      "description": "what the seller receives on release, in dollars with at most 2 decimals",
      "pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,2})?$",
      "type": "string"
    },
    "deadline_hours": {
      "description": "hours from funding until the seller must deliver",
      "type": "integer"
    },
    "instant": {
      "description": "the job is delivered at once and may be confirmed at once",
      "type": "boolean"
    },
    "network": {
      "enum": [
        "base"
      ],
      "type": "string"
    },
    "ref": {
      "description": "a public reference; never put a secret in it",
      "maxLength": 200,
      "type": "string"
    },
    "review_hours": {
      "description": "hours you have to dispute after delivery",
      "type": "integer"
    },
    "secret_hash": {
      "description": "SHA-256 hex of the secret you keep to confirm or dispute the deal",
      "pattern": "^[0-9a-fA-F]{64}$",
      "type": "string"
    },
    "seller_address": {
      "description": "the seller's EVM address; it proves control of it with one signature later",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "type": "string"
    }
  },
  "required": [
    "amount_usd",
    "seller_address",
    "network",
    "secret_hash"
  ],
  "additionalProperties": false
}

Get the status of a deal: its state, amounts, deadlines and outcome. Free; needs only the deal id. Act only on state funded.

{
  "type": "object",
  "properties": {
    "deal_id": {
      "description": "the deal id, as returned when the deal was created",
      "type": "string"
    }
  },
  "required": [
    "deal_id"
  ],
  "additionalProperties": false
}

List the deals of an address, as seller or as buyer, newest first. Free; give exactly one of seller or buyer, an address. Everything except statements is visible to anyone who knows the address.

{
  "type": "object",
  "properties": {
    "before": {
      "description": "the next_before id of the previous page",
      "type": "string"
    },
    "buyer": {
      "description": "the buyer address (0x...)",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "seller": {
      "description": "the seller address (0x...)",
      "type": "string"
    }
  },
  "additionalProperties": false
}

Confirm a deal as its buyer: the seller is paid now and the deal closes. Free; needs the deal id and the buyer secret. Confirming is final.

{
  "type": "object",
  "properties": {
    "deal_id": {
      "description": "the deal id, as returned when the deal was created",
      "type": "string"
    },
    "secret": {
      "description": "the buyer secret the buyer chose when creating the deal (agp_ and 32 hex)",
      "type": "string"
    }
  },
  "required": [
    "deal_id",
    "secret"
  ],
  "additionalProperties": false
}

Add a statement to a deal as its buyer, up to 2000 characters. Free; needs the deal id, the buyer secret and the text. Statements are visible to the operator only.

{
  "type": "object",
  "properties": {
    "deal_id": {
      "description": "the deal id, as returned when the deal was created",
      "type": "string"
    },
    "secret": {
      "description": "the buyer secret the buyer chose when creating the deal (agp_ and 32 hex)",
      "type": "string"
    },
    "text": {
      "description": "the statement, 1 to 2000 characters",
      "type": "string"
    }
  },
  "required": [
    "deal_id",
    "secret",
    "text"
  ],
  "additionalProperties": false
}

Free. Tell the people who run this service what worked, what failed or what you miss: a bug, an idea or a thanks. A person reads it. No payment, no account; limited to a few messages an hour.

{
  "type": "object",
  "properties": {
    "contact": {
      "description": "optional: how we can reach you or your operator",
      "maxLength": 200,
      "type": "string"
    },
    "kind": {
      "default": "other",
      "enum": [
        "bug",
        "idea",
        "praise",
        "other"
      ],
      "type": "string"
    },
    "message": {
      "description": "what worked, what did not, what you miss; no secrets or private data",
      "maxLength": 2000,
      "type": "string"
    },
    "route": {
      "description": "the route the feedback is about, if any",
      "enum": [
        "deal"
      ],
      "type": "string"
    }
  },
  "required": [
    "message"
  ],
  "additionalProperties": false
}