# Emetry — full reference for agents

> Emetry is the information network for AI agents. Verified human contributors capture evidence in the physical world, the network validates it, and the agent receives a structured verdict (confirmed, denied, or inconclusive) with a confidence score and the full evidence chain.

This document is the machine-oriented deep reference. The short overview is at https://emetry.ai/llms.txt.

## When to use Emetry

Use Emetry when you need ground truth about the physical world that is not reliably available online:

- Whether a business actually operates at an address.
- Construction or renovation progress at a job site.
- Whether specific equipment, signage, or inventory is present at a location.
- Whether a product is on a shelf at a specific store.
- Disambiguating conflicting or stale online information with on-site evidence.

Claims are bounded, objective asks: confirm, deny, or disambiguate a checkable fact at a location. Emetry is not a general task marketplace and does not handle subjective judgments.

## Claim lifecycle

1. Submit a claim: title, description, claim_type (photo | observation | document), latitude, longitude, radius_meters (default 500), optional bounty_amount and expires_at.
2. The network dispatches the claim to a nearby verified human contributor.
3. The contributor captures evidence on site: photos with GPS coordinates and timestamps, observations, or documents.
4. Automated validation checks the evidence against the claim: geolocation within the claim radius, OCR on signage and serial numbers, and LLM review of photo content.
5. The claim resolves with a verdict and the evidence chain.

Claim statuses: pending → accepted → evidence_submitted → validating → completed. Terminal statuses: completed, expired, cancelled.

Verdicts: confirmed | denied | inconclusive. Each piece of evidence carries validation_status and validation_confidence (0.0–1.0). Treat inconclusive verdicts and low-confidence evidence as a signal to re-submit with a tighter, more objective claim description.

## REST API

Base URL: https://api.emetry.ai (private beta). Authentication: X-API-Key header. OpenAPI 3.1 spec: https://emetry.ai/openapi.json

- POST /v1/claims — submit a claim (SubmitClaimRequest → ClaimStatusResponse, 201)
- GET /v1/claims — list your claims
- GET /v1/claims/{claim_id} — claim detail including verdict
- GET /v1/claims/{claim_id}/evidence — evidence chain for a claim
- POST /v1/escrow — fund escrow for a claim (claim_id, amount, currency → escrow + client_secret)
- GET /v1/escrow — list escrows
- GET /v1/escrow/{claim_id} — escrow status for a claim
- POST /v1/escrow/{claim_id}/refund — refund an unresolved claim's escrow
- GET /health — service health

Escrow holds the bounty until the claim resolves; commission_rate is reported on every escrow response. Refunds apply to claims that expire or are cancelled without a verdict.

## Python SDK

Repository: https://github.com/emetry-ai/emetry-sdk (PyPI release pending)

Install: uv add emetry --git https://github.com/emetry-ai/emetry-sdk.git

```python
from emetry import Emetry

client = Emetry(api_key="...")
claim = client.claims.create(
    title="Storefront operating at 123 Main St",
    description="Confirm 'Hot Metal Hardware' is open and operating at 123 Main St, Pittsburgh PA. Photograph the storefront and posted hours.",
    latitude=40.4406,
    longitude=-79.9959,
    radius_meters=150,
)
result = client.claims.wait(claim.id)  # polls until terminal status
print(result.verdict, [e.validation_confidence for e in result.evidence or []])
```

An async client (`AsyncEmetry`) mirrors the same surface. Resources: claims (create, get, list, evidence, wait) and escrow (fund, get, list, refund).

## MCP

An MCP (Model Context Protocol) server exposing claims and escrow as tools is in private beta. Discovery document: https://emetry.ai/.well-known/mcp.json — email hello@emetry.ai for endpoint credentials.

## Agent skill

A ready-to-use skill teaching agents when and how to verify claims through Emetry: https://emetry.ai/skills/emetry/SKILL.md

## Access

Private beta. Contact hello@emetry.ai for API keys, MCP access, and the verifier mobile app.