Onsight API: open-source docs + x402 agent example

ktamas77 · claude · ktamas77 · commit dcb9f74c6b70 · 2026-07-10T00:27:56.000-07:00
Ground-truth photo API for AI agents and humans. Documents the x402
agent channel (pay USDC per photo order on Base), the wallet-signature
owner-action auth, and the human web flow. Includes a runnable
x402-fetch agent order example.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,5 @@
+node_modules/
+.env
+.env.*
+*.log
+.DS_Store
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,48 @@
+# Contributing to Onsight API
+
+Thanks for taking the time. This repo is the **public documentation and examples**
+for the Onsight API — the service itself lives at [onsight.photo](https://onsight.photo).
+Contributions here are about making the API easier to use.
+
+## What to open an issue about
+
+- **Docs that are wrong or unclear** — an endpoint, header, or payment step that
+  doesn't match what the API actually does. Include the request you sent and the
+  response you got (redact wallet keys and signatures).
+- **Broken examples** — if [`examples/`](examples/) doesn't run, tell us your Node
+  version, the command you ran, and the full error.
+- **API bugs** — unexpected status codes, wrong prices in a `402`, settlement or
+  payout problems. Include the mission id and, if payment-related, the on-chain
+  `txHash` (public info, safe to share).
+- **Questions about integrating** — how to call it from your agent framework,
+  language, or wallet setup. No such thing as a dumb one.
+
+## Requesting an API feature
+
+Open an issue titled `[feature] ...` and cover:
+
+- **The job to be done** — what your agent or app is trying to accomplish.
+- **Why the current API can't** — the missing endpoint, field, filter, or payment mode.
+- **A sketch of the shape** — the request/response you'd want, if you have one in mind.
+
+Concrete use cases move fastest. "My agent needs to filter open missions by radius"
+beats "please add filtering".
+
+## Pull requests
+
+For docs and examples in this repo, PRs are welcome:
+
+1. Fork and branch.
+2. Keep changes focused — one fix or example per PR.
+3. If you touch [`examples/`](examples/), make sure it still runs
+   (`cd examples && npm install && node <file>`).
+4. Open the PR with a short description of what and why.
+
+## Security
+
+Found a vulnerability — in the payment flow, escrow, or wallet-signature auth?
+**Don't open a public issue.** See [SECURITY.md](SECURITY.md).
+
+## Code of conduct
+
+Be decent. Assume good faith, keep it about the work, and help newcomers.
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 squidcode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -0,0 +1,123 @@
+# Onsight API
+
+**Photo infrastructure for AI agents and humans.** Onsight lets you commission a
+real, verified, geotagged photo of a specific place at a specific time — and pay
+for it per request. An AI agent can't walk outside and photograph a storefront,
+a parking lot, or a shelf. Onsight is the API that can.
+
+Live at **[onsight.photo](https://onsight.photo)**.
+
+---
+
+## What Onsight is
+
+Onsight is a crowdsourced ground-truth photography marketplace:
+
+- A **requester** posts a *mission* — "photograph the queue outside this address,
+  today, from the street" — and funds a reward in USDC.
+- Local **photographers** nearby fulfill it and submit photos.
+- The requester picks a winner; the escrowed reward pays out on-chain.
+
+There are **two front doors onto the same rail**:
+
+| Requester | How they order | How they pay |
+|---|---|---|
+| **Human** | web UI at [onsight.photo](https://onsight.photo) | direct USDC deposit (card on-ramp available) |
+| **AI agent** | `POST /agent/missions` | **[x402](https://x402.org)** — pays USDC per call, no account, no key |
+
+Same escrow, same photographer supply, same payout. Only how the order is placed
+and paid differs.
+
+## Why agents need it
+
+Agents are good at reasoning over data they're given and terrible at the physical
+world. They can't verify a place is real, open, busy, or gone. Onsight closes that
+gap: one paid API call returns a fresh, geotagged photograph taken by a real person
+on the ground. It's a ground-truth sensor for the physical world, priced per photo.
+
+## How agent payment works (x402)
+
+[x402](https://x402.org) is the "HTTP 402 Payment Required" standard — the server
+answers a paid request with a `402` and a price, the client pays inline and retries.
+No signup, no API key: **the agent's wallet _is_ the account.**
+
+```
+1. Agent    →  POST /agent/missions?rewardUsd=20   (mission body, no payment)
+2. Onsight  →  402 Payment Required { price: $20 USDC, payTo: treasury, network: Base }
+3. Agent    →  signs an EIP-3009 authorization, retries with an X-PAYMENT header
+4. Onsight  →  verifies + settles USDC on-chain → mission created & funded (escrow)
+               returns the mission + the settlement txHash
+```
+
+Settlement runs through a standard x402 **facilitator** (x402.org on testnet,
+Coinbase CDP on mainnet) — Onsight runs no extra chain infrastructure. Payment is
+on **[Base](https://base.org)** in **USDC**.
+
+> **x402 gates money _in_. A wallet signature gates every owner action.**
+
+Once a mission is funded, the agent proves ownership of subsequent actions (edit the
+brief, pick a winner, refund) by signing a request with the same wallet — no more
+payments, since the money is already escrowed.
+
+## API surface
+
+Base URL: `https://onsight.photo`
+
+| Agent action | Endpoint | Auth |
+|---|---|---|
+| Post + fund a mission (place a photo order) | `POST /agent/missions?rewardUsd=N` | **x402** (payment = escrow funding) |
+| Read a mission + submitted photos | `GET /agent/missions/:id` | public |
+| Update brief / extend dates | `PATCH /agent/missions/:id` | wallet signature |
+| Pick + pay a winner | `POST /agent/missions/:id/select` `{ photoId }` | wallet signature |
+| Refund / cancel | `POST /agent/missions/:id/refund` | wallet signature |
+
+**Wallet-signature auth** (owner actions): send `X-Wallet-Address`,
+`X-Wallet-Signature`, and `X-Wallet-Timestamp`, signing the message
+
+```
+Onsight agent: {METHOD} {path} @ {timestamp} body={sha256(body)}
+```
+
+The signature is action-, time-, and body-bound (5-minute window), so a captured
+`select` signature can't be replayed with a swapped `photoId`.
+
+## Quick start
+
+Get a `402` quote for a $20 photo mission — no wallet required to see the price:
+
+```bash
+curl -i -X POST "https://onsight.photo/agent/missions?rewardUsd=20" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Storefront at 123 Market St",
+    "description": "Street-level photo of the entrance, taken today in daylight.",
+    "lat": 37.7897,
+    "lng": -122.3972,
+    "radiusMeters": 150
+  }'
+# → HTTP/1.1 402 Payment Required
+# → body describes price, payTo (treasury), asset (USDC), and network (Base)
+```
+
+To actually place and fund the order, an agent signs the payment and retries with an
+`X-PAYMENT` header. The full runnable flow — using [`x402-fetch`](https://www.npmjs.com/package/x402-fetch)
+so payment is handled automatically — is in
+**[`examples/x402-agent-order.js`](examples/x402-agent-order.js)**.
+
+Buying as a human? See **[`examples/human-order.md`](examples/human-order.md)**.
+
+## Examples
+
+- [`examples/x402-agent-order.js`](examples/x402-agent-order.js) — an agent places and
+  funds a photo order via x402, then reads it back.
+- [`examples/human-order.md`](examples/human-order.md) — walkthrough for human buyers.
+
+## Status
+
+The USDC escrow rail is live on Base mainnet; the x402 agent channel is rolling out.
+Endpoints and payloads here track the public API — if something drifts,
+[open an issue](../../issues).
+
+## License
+
+[MIT](LICENSE) © squidcode
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,19 @@
+# Security Policy
+
+Onsight moves real money (USDC escrow on Base) and authenticates owner actions with
+wallet signatures. If you find a vulnerability in the payment flow, escrow, refund,
+or signature-auth logic, we want to hear from you.
+
+## Reporting
+
+**Do not open a public issue for security vulnerabilities.**
+
+- Email **security@onsight.photo**, or
+- Use GitHub's [private vulnerability reporting](../../security/advisories/new).
+
+Please include enough to reproduce: the request, the response, and (for
+payment/settlement issues) the on-chain `txHash` — which is public and safe to share.
+Do **not** include private keys or signatures from a real funded wallet.
+
+We'll acknowledge within a few business days and keep you posted on the fix. Please
+give us a reasonable window to patch before any public disclosure.
diff --git a/examples/human-order.md b/examples/human-order.md
@@ -0,0 +1,29 @@
+# Ordering a photo as a human
+
+You don't need a crypto wallet, an agent, or the API to buy a photo on Onsight.
+The web app wraps the same escrow rail the agent API uses.
+
+## Steps
+
+1. **Go to [onsight.photo](https://onsight.photo)** and start a new mission.
+2. **Describe what you need.** A good brief is specific:
+   - *What* to photograph (a storefront, a line, a shelf, a view).
+   - *Where* — an address or a dropped map pin, plus how far around it is acceptable.
+   - *When* — "today", "during business hours", a specific date/time window.
+   - Any constraints — daylight, no faces, a particular angle.
+3. **Set the reward.** This is what the winning photographer earns. Higher rewards
+   and tighter deadlines get filled faster.
+4. **Fund it.** Pay the reward into escrow — with USDC directly, or by card via the
+   built-in on-ramp if you don't hold crypto. The money is held, not spent yet.
+5. **Wait for submissions.** Nearby photographers get the mission and submit photos.
+   You'll see them come in on the mission page.
+6. **Pick the winner.** Select the best photo. The escrowed reward pays out to that
+   photographer automatically; unspent funds can be refunded.
+
+## How it relates to the agent API
+
+Everything above is the human front door to the exact rail described in the
+[README](../README.md): funding a mission = escrow, picking a winner = payout. An AI
+agent does the same three things — post, fund, select — over
+[x402](https://x402.org) instead of a web form. See
+[`x402-agent-order.js`](x402-agent-order.js).
diff --git a/examples/package.json b/examples/package.json
@@ -0,0 +1,10 @@
+{
+  "name": "onsight-api-examples",
+  "private": true,
+  "type": "module",
+  "description": "Runnable examples for the Onsight API",
+  "dependencies": {
+    "viem": "^2.54.3",
+    "x402-fetch": "^0.6.0"
+  }
+}
diff --git a/examples/x402-agent-order.js b/examples/x402-agent-order.js
@@ -0,0 +1,59 @@
+// Place and fund a ground-truth photo order on Onsight, paid via x402.
+//
+// An AI agent can't photograph a real place — this commissions a real person to.
+// x402 handles payment inline: the first request comes back 402, `x402-fetch`
+// signs a USDC payment on Base and retries automatically. The agent's wallet IS
+// the account — no signup, no API key.
+//
+// Run:
+//   cd examples && npm install
+//   AGENT_PRIVATE_KEY=0x... node x402-agent-order.js
+//
+// The wallet needs USDC on Base (or Base Sepolia for testing) plus a little ETH
+// for the on-chain settlement.
+
+import { wrapFetchWithPayment } from "x402-fetch";
+import { privateKeyToAccount } from "viem/accounts";
+
+const BASE_URL = process.env.ONSIGHT_URL ?? "https://onsight.photo";
+const REWARD_USD = 20;
+
+const key = process.env.AGENT_PRIVATE_KEY;
+if (!key) throw new Error("Set AGENT_PRIVATE_KEY to a wallet holding USDC on Base");
+
+const account = privateKeyToAccount(key);
+// fetch that transparently answers a 402 by paying and retrying:
+const fetchWithPay = wrapFetchWithPayment(fetch, account);
+
+const mission = {
+  title: "Storefront at 123 Market St",
+  description: "Street-level photo of the entrance, taken today in daylight.",
+  lat: 37.7897,
+  lng: -122.3972,
+  radiusMeters: 150,
+};
+
+// 1. Post + fund the mission. First call → 402; x402-fetch pays and retries.
+const res = await fetchWithPay(`${BASE_URL}/agent/missions?rewardUsd=${REWARD_USD}`, {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify(mission),
+});
+
+if (!res.ok) {
+  throw new Error(`Order failed: ${res.status} ${await res.text()}`);
+}
+
+const created = await res.json();
+console.log("Mission funded:", created.id);
+console.log("Settlement tx:", created.txHash ?? created.paymentTxHash);
+
+// 2. Read it back (public — no payment, no signature needed) to poll for photos.
+const check = await fetch(`${BASE_URL}/agent/missions/${created.id}`);
+const state = await check.json();
+console.log(`Status: ${state.status ?? state.paymentStatus} — ${(state.photos ?? []).length} photo(s) so far`);
+
+// Next steps (owner actions, gated by a wallet signature rather than x402):
+//   POST /agent/missions/:id/select  { photoId }   → pick + pay the winner
+//   POST /agent/missions/:id/refund                → cancel + refund the escrow
+// See the README's "Wallet-signature auth" section for the signing scheme.

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +node_modules/
 +.env
 +.env.*
 +*.log
 +.DS_Store