{
 "openapi": "3.1.0",
 "info": {
  "title": "5arz Proof-of-Human API",
  "version": "1.0.0",
  "summary": "Prove a real, unique, attentive human performed an action \u2014 and get a signed, independently verifiable credential.",
  "description": "5arz is the proof-of-human layer for the internet. It issues **Proof-of-Human-Fulfillment (PoHF)** credentials: ES256-signed JWTs asserting that a real, unique, attentive human \u2014 not a bot or AI agent \u2014 performed a specific action (work, a view, a presence event, or a personhood check). Anyone can verify a credential against the public JWKS at https://api.5arz.com/.well-known/jwks.json using any standard JWT library \u2014 no 5arz SDK and no trust in 5arz required. Use it for AI training data provenance, verified human traffic / ad-fraud defense, anti-sybil and proof-of-personhood gating for DeFi/RWA, KYC-style human checks in your product, and the fulfillment half of agentic commerce (proving a human did the work an AI agent paid for). Verifications are prepaid credits; free `arz_test_` keys verify unlimited for integration. Compatible with Verifiable Intent and the Visa Trusted Agent Protocol; settles over Agent Pay, Stripe, or USDC.",
  "termsOfService": "https://5arz.com/terms",
  "contact": {
   "name": "5arz",
   "email": "info@5arz.com",
   "url": "https://5arz.com/docs"
  },
  "license": {
   "name": "Proprietary \u2014 Patents pending US 63/979,052 + US 63/979,474"
  }
 },
 "servers": [
  {
   "url": "https://api.5arz.com",
   "description": "Production"
  }
 ],
 "externalDocs": {
  "description": "Developer docs & SDK",
  "url": "https://5arz.com/docs"
 },
 "security": [
  {
   "bearerAuth": []
  }
 ],
 "tags": [
  {
   "name": "Auth & credits",
   "description": "Register, buy prepaid verification credits, check balance."
  },
  {
   "name": "Verification",
   "description": "Mint signed Proof-of-Human credentials for a session, a person, or physical presence."
  },
  {
   "name": "Attestation",
   "description": "Prove a genuine device (not an emulator) and strengthen a credential."
  },
  {
   "name": "Tracking & metrics",
   "description": "Attach proof to on-site actions and conversions; read verified-attention analytics."
  },
  {
   "name": "Tasks",
   "description": "Fetch and complete embeddable micro-tasks that mint credentials."
  },
  {
   "name": "Partner",
   "description": "Convert reward points to Stars, read balances, request payouts."
  },
  {
   "name": "Keys",
   "description": "Public keys for verifying 5arz credentials anywhere."
  },
  {
   "name": "Agentic commerce",
   "description": "Commission verified human work and bind a verified human to a payment on any rail (OUSD, Mastercard Agent Pay, Stripe, USDC). MCP: https://api.5arz.com/mcp"
  },
  {
   "name": "Index",
   "description": "VHH \u2014 Verified Human Hour reference rates. Free composite; licensed categories/history. https://5arz.com/vhh-index"
  },
  {
   "name": "Forwards",
   "description": "Prepaid verified-human-hours capacity at VHH-referenced prices."
  }
 ],
 "paths": {
  "/api/agents/register": {
   "post": {
    "tags": [
     "Auth & credits"
    ],
    "operationId": "register",
    "summary": "Create an API key",
    "description": "Self-serve registration. Returns an API key shown once. Pass `mode:\"test\"` for a free `arz_test_` sandbox key that verifies unlimited and mints credentials marked `test:true` (never treat test credentials as production proof).",
    "security": [],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "name",
         "contactEmail"
        ],
        "properties": {
         "name": {
          "type": "string",
          "example": "Your Company"
         },
         "contactEmail": {
          "type": "string",
          "format": "email",
          "example": "you@company.com"
         },
         "mode": {
          "type": "string",
          "enum": [
           "live",
           "test"
          ],
          "default": "live"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Key created (shown once).",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "apiKey": {
           "type": "string",
           "example": "arz_live_\u2026"
          },
          "agentId": {
           "type": "string",
           "example": "agt_\u2026"
          },
          "mode": {
           "type": "string",
           "enum": [
            "live",
            "test"
           ]
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/agents/credits/buy": {
   "post": {
    "tags": [
     "Auth & credits"
    ],
    "operationId": "buyCredits",
    "summary": "Buy a prepaid verification pack",
    "description": "Returns a Stripe checkout URL. Credits post on payment. Test keys skip this (unlimited free). Packs: starter 100/$49, growth 1,000/$299, scale 10,000/$1,999.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "pack"
        ],
        "properties": {
         "pack": {
          "type": "string",
          "enum": [
           "starter",
           "growth",
           "scale"
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Checkout created.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "checkoutUrl": {
           "type": "string",
           "format": "uri"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/agents/credits/balance": {
   "get": {
    "tags": [
     "Auth & credits"
    ],
    "operationId": "creditsBalance",
    "summary": "Remaining verifications",
    "responses": {
     "200": {
      "description": "Balance.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "balance": {
           "type": "integer"
          },
          "lifetimePurchased": {
           "type": "integer"
          },
          "lifetimeConsumed": {
           "type": "integer"
          },
          "packs": {
           "type": "array",
           "items": {
            "type": "object"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/agents/verify": {
   "post": {
    "tags": [
     "Verification"
    ],
    "operationId": "verifyHuman",
    "summary": "Mint a Proof-of-Human-Fulfillment credential",
    "description": "Attest that a verified human session performed a unit of work. Spends 1 credit. Returns a signed ES256 PoHF JWT plus quality score and tamper-evident telemetry. Returns 402 (with a buy link) if no credits.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "sessionId"
        ],
        "properties": {
         "sessionId": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Signed credential.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Credential"
        }
       }
      }
     },
     "402": {
      "description": "No credits.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/agents/verify-personhood": {
   "post": {
    "tags": [
     "Verification"
    ],
    "operationId": "verifyPersonhood",
    "summary": "Mint a Proof-of-Personhood credential",
    "description": "Prove a real, unique, live human (anti-sybil). Spends 1 credit. Optionally bind an EVM wallet (see /api/agents/wallet/challenge) to add a `wallet` claim for on-chain isVerifiedHuman() gating.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "memberId"
        ],
        "properties": {
         "memberId": {
          "type": "string"
         },
         "wallet": {
          "type": "string",
          "description": "EVM address (optional)"
         },
         "walletSig": {
          "type": "string",
          "description": "EIP-191 personal_sign of the challenge (optional)"
         },
         "walletNonce": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Signed personhood credential.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Credential"
        }
       }
      }
     }
    }
   }
  },
  "/api/kinetic/submit": {
   "post": {
    "tags": [
     "Verification"
    ],
    "operationId": "kineticSubmit",
    "summary": "Prove physical presence",
    "description": "Submit a receipt or geo-tagged photo as physical-presence evidence. Scored into a session; mint a credential via /api/agents/verify. One-time-use per photo hash.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "memberId",
         "source"
        ],
        "properties": {
         "memberId": {
          "type": "string"
         },
         "source": {
          "type": "string",
          "enum": [
           "receipt",
           "geo_photo"
          ]
         },
         "lat": {
          "type": "number"
         },
         "lng": {
          "type": "number"
         },
         "photoHash": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Scored session."
     }
    }
   }
  },
  "/api/agents/attest/challenge": {
   "post": {
    "tags": [
     "Attestation"
    ],
    "operationId": "attestChallenge",
    "summary": "Device attestation \u2014 step 1",
    "description": "Returns a one-time nonce/challenge for anti-replay device attestation.",
    "responses": {
     "200": {
      "description": "Challenge.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "nonce": {
           "type": "string"
          },
          "challengeB64url": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/agents/attest/verify": {
   "post": {
    "tags": [
     "Attestation"
    ],
    "operationId": "attestVerify",
    "summary": "Device attestation \u2014 step 2",
    "description": "Prove a genuine device (not an emulator). Attested devices add a `device` claim to credentials.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "method",
         "nonce",
         "subjectRef"
        ],
        "properties": {
         "method": {
          "type": "string",
          "enum": [
           "webauthn",
           "play_integrity",
           "app_attest"
          ]
         },
         "nonce": {
          "type": "string"
         },
         "subjectRef": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Attestation result.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "attested": {
           "type": "boolean"
          },
          "assurance": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/track/event": {
   "post": {
    "tags": [
     "Tracking & metrics"
    ],
    "operationId": "trackEvent",
    "summary": "Public behavior beacon",
    "description": "Cookieless, sendBeacon-friendly on-site behavior tied to a verified view (`vt`). Emitted by the post-click tag.",
    "security": [],
    "responses": {
     "200": {
      "description": "Recorded."
     }
    }
   }
  },
  "/api/agents/track/conversion": {
   "post": {
    "tags": [
     "Tracking & metrics"
    ],
    "operationId": "trackConversion",
    "summary": "Server-side conversion tied to a verified view",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "vt",
         "name"
        ],
        "properties": {
         "vt": {
          "type": "string",
          "description": "verified-view token"
         },
         "name": {
          "type": "string",
          "example": "purchase"
         },
         "value": {
          "type": "number"
         },
         "currency": {
          "type": "string",
          "example": "USD"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Attribution result.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "attributed": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/agents/metrics": {
   "get": {
    "tags": [
     "Tracking & metrics"
    ],
    "operationId": "metrics",
    "summary": "Verified-attention analytics",
    "description": "Summary + per-view rows (focus, probe, input, gaze, quality, fraud flags), each tagged with its credential id.",
    "parameters": [
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "csv"
       ]
      }
     },
     {
      "name": "since",
      "in": "query",
      "schema": {
       "type": "string",
       "format": "date-time"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Metrics."
     }
    }
   }
  },
  "/api/agents/metrics/funnel": {
   "get": {
    "tags": [
     "Tracking & metrics"
    ],
    "operationId": "metricsFunnel",
    "summary": "Verified funnel (views \u2192 landed \u2192 engaged \u2192 conversions)",
    "responses": {
     "200": {
      "description": "Funnel with rates + value."
     }
    }
   }
  },
  "/api/tasks/next": {
   "get": {
    "tags": [
     "Tasks"
    ],
    "operationId": "tasksNext",
    "summary": "Fetch an embeddable micro-task",
    "security": [],
    "parameters": [
     {
      "name": "site",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "agentId"
     }
    ],
    "responses": {
     "200": {
      "description": "A task.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "task": {
           "type": "object"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/tasks/complete": {
   "post": {
    "tags": [
     "Tasks"
    ],
    "operationId": "tasksComplete",
    "summary": "Submit a task completion",
    "description": "Public. A verified completion (answer + attention) mints a PoHF via /api/agents/verify.",
    "security": [],
    "responses": {
     "200": {
      "description": "Completion recorded."
     }
    }
   }
  },
  "/api/agents/wallet/challenge": {
   "post": {
    "tags": [
     "Verification"
    ],
    "operationId": "walletChallenge",
    "summary": "On-chain personhood \u2014 get a message to sign",
    "responses": {
     "200": {
      "description": "Nonce + message.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "nonce": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/agents/webhooks": {
   "post": {
    "tags": [
     "Auth & credits"
    ],
    "operationId": "registerWebhook",
    "summary": "Register a push webhook",
    "description": "HMAC-signed (X-5arz-Signature). Fires events such as personhood.wallet_bound.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "url",
         "events"
        ],
        "properties": {
         "url": {
          "type": "string",
          "format": "uri"
         },
         "events": {
          "type": "array",
          "items": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Webhook registered (signingSecret shown once).",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "string"
          },
          "signingSecret": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/partner/points/convert": {
   "post": {
    "tags": [
     "Partner"
    ],
    "operationId": "partnerPointsConvert",
    "summary": "Convert reward points to Stars",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "userRef",
         "points"
        ],
        "properties": {
         "userRef": {
          "type": "string"
         },
         "points": {
          "type": "number"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Idempotent. New balance.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "balance": {
           "type": "number"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/partner/payout/request": {
   "post": {
    "tags": [
     "Partner"
    ],
    "operationId": "partnerPayoutRequest",
    "summary": "Queue a Stars \u2192 cash payout",
    "description": "Reviewed; no auto-transfer.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "userRef",
         "stars"
        ],
        "properties": {
         "userRef": {
          "type": "string"
         },
         "stars": {
          "type": "number"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Queued.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "requestId": {
           "type": "string"
          },
          "status": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/.well-known/jwks.json": {
   "get": {
    "tags": [
     "Keys"
    ],
    "operationId": "jwks",
    "summary": "Public keys",
    "description": "Verify any 5arz credential's ES256 signature against these keys \u2014 no 5arz software required.",
    "security": [],
    "responses": {
     "200": {
      "description": "JWK Set.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/workflows/available": {
   "get": {
    "operationId": "listVerifiedWork",
    "summary": "List commissionable verified-work tasks.",
    "responses": {
     "200": {
      "description": "OK"
     }
    },
    "tags": [
     "Agentic commerce"
    ]
   }
  },
  "/api/agents/order": {
   "post": {
    "operationId": "commissionWork",
    "summary": "Commission verified human work.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "taskType": {
          "type": "string"
         },
         "quantity": {
          "type": "number"
         },
         "maxPriceUsd": {
          "type": "number"
         }
        },
        "required": [
         "taskType",
         "quantity"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Order created"
     },
     "401": {
      "description": "Auth required"
     }
    },
    "tags": [
     "Agentic commerce"
    ]
   }
  },
  "/api/agents/bind-transaction": {
   "post": {
    "operationId": "bindHumanToPayment",
    "summary": "Bind a verified human to a Tempo/OUSD/Agent Pay/Stripe/USDC payment; returns a signed credential. Pass test:true to try without a live payment.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "paymentRef": {
          "type": "string"
         },
         "sessionId": {
          "type": "string"
         },
         "memberId": {
          "type": "string"
         },
         "workRef": {
          "type": "string"
         },
         "test": {
          "type": "boolean"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Signed binding credential"
     },
     "400": {
      "description": "Missing payment/human anchor"
     },
     "401": {
      "description": "Auth required"
     }
    },
    "tags": [
     "Agentic commerce"
    ]
   }
  },
  "/api/index": {
   "get": {
    "tags": [
     "Index"
    ],
    "operationId": "indexCatalog",
    "summary": "VHH index catalog \u2014 published codes with latest final epoch (free, cached).",
    "security": [],
    "responses": {
     "200": {
      "description": "Catalog"
     }
    }
   }
  },
  "/api/index/vhh": {
   "get": {
    "tags": [
     "Index"
    ],
    "operationId": "indexVhh",
    "summary": "VHH composite. Free: latest final epoch, ES256-signed (verify against /.well-known/jwks.json). With an agent API key: current MTD + categories + ?history=1.",
    "security": [],
    "responses": {
     "200": {
      "description": "Signed epoch"
     },
     "403": {
      "description": "Licensed tier requires API key"
     }
    }
   }
  },
  "/api/index/{code}": {
   "get": {
    "tags": [
     "Index"
    ],
    "operationId": "indexByCode",
    "summary": "Any VHH_* category series (licensed \u2014 agent API key).",
    "parameters": [
     {
      "name": "code",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "VHH_content_mod"
     }
    ],
    "responses": {
     "200": {
      "description": "Series"
     },
     "403": {
      "description": "License required"
     }
    }
   }
  },
  "/api/forwards/order": {
   "post": {
    "tags": [
     "Forwards"
    ],
    "operationId": "forwardOrder",
    "summary": "Order prepaid verified-human-hours capacity (category, hours, month) at a VHH-referenced price. Intake only \u2014 countersigned service agreement + Stripe invoice follow. Not transferable, not resellable, not cash-settled.",
    "security": [],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "name",
         "company",
         "email",
         "hours",
         "month"
        ],
        "properties": {
         "name": {
          "type": "string"
         },
         "company": {
          "type": "string"
         },
         "email": {
          "type": "string"
         },
         "category": {
          "type": "string"
         },
         "hours": {
          "type": "number"
         },
         "month": {
          "type": "string",
          "example": "2026-08"
         },
         "notes": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Order received with capacity assessment + indicative price"
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "arz_live_\u2026 / arz_test_\u2026",
    "description": "Authorization: Bearer <apiKey>. Required on all endpoints except register, public track/tasks beacons, and jwks."
   }
  },
  "schemas": {
   "Credential": {
    "type": "object",
    "description": "A Proof-of-Human credential response.",
    "properties": {
     "pohf_jwt": {
      "type": "string",
      "description": "ES256-signed compact JWT. Verify against the public JWKS."
     },
     "verified": {
      "type": "boolean"
     },
     "quality": {
      "type": "number",
      "description": "0\u20131 human-attention quality score"
     },
     "credentialId": {
      "type": "string"
     }
    }
   },
   "Error": {
    "type": "object",
    "properties": {
     "ok": {
      "type": "boolean",
      "example": false
     },
     "error": {
      "type": "string"
     },
     "buy": {
      "type": "string",
      "format": "uri",
      "description": "Present on 402 \u2014 link to buy credits."
     }
    }
   }
  }
 }
}