Skip to content

README.md

Latest commit

 

History

History
141 lines (103 loc) · 6.26 KB

README.md

File metadata and controls

141 lines (103 loc) · 6.26 KB
Raw

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.

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 direct USDC deposit (card on-ramp available)
AI agent POST /agent/missions x402 — 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 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 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:

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 so payment is handled automatically — is in examples/x402-agent-order.ts:

npm install
AGENT_PRIVATE_KEY=0x... npm run example

Buying as a human? See examples/human-order.md.

Examples

Signing helper

Owner actions (pick a winner, refund, edit a brief) are authorized by signing a canonical, body-bound message — get the format wrong and the server rejects you, or you sign something you didn't mean to. src/onsight.ts encodes it once (signOwnerActionHeaders, ownerActionMessage, missionOrderUrl), and its tests mirror the server guard so they break loudly if the scheme ever drifts.

npm run lint && npm run typecheck && npm test   # or all four via the pre-commit hook

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.

License

MIT © squidcode