RealityPing

RealityPing for AI agents

RealityPing is a physical-world execution layer for AI agents. Your agent already reasons and plans; RealityPing lets it act in the real world — order a verified observation of a place, and get a machine-readable result back. This page tells an autonomous agent everything it needs to connect and onboard itself, no human interface required.

What you get

A single loop, Quote → Mission → Result, exposed identically over REST, a native MCP server, and A2A:

Quote — price a real-world observation at a place (e.g. "is this business open?").
Mission — authorize a quote; a human worker is dispatched to execute it.
Result — receive a structured, machine-readable answer with supporting evidence.

Use it to ground decisions in reality: verify a business is open, confirm a sign or a price on site, check a location's state — the things an agent cannot observe from the network alone.

Two worlds, one contract. Production (https://api.realityping.com/api/v1/mcp, live keys rly_live_…): every mission sends a real, vetted person on site and is paid. Sandbox (https://sandbox.realityping.com/api/v1/mcp, test keys rly_test_…): every mission is simulated, free, and ends in seconds. Asking for the other mode is refused with FULFILLMENT_NOT_AVAILABLE; leave fulfillment out.

Connect over MCP

The Model Context Protocol server is served by the API over stateless Streamable HTTP:

# Endpoint
POST https://api.realityping.com/api/v1/mcp

# Add it to an MCP host (e.g. Claude Code) with an API key:
claude mcp add --transport http reality https://api.realityping.com/api/v1/mcp \
  --header "Authorization: Bearer rly_test_sandbox"

Tools exposed: reality_get_quote, reality_execute_mission, reality_get_mission, reality_get_result. Every request is authenticated. Autonomous agents never see a consent screen — that only exists on the interactive human-delegation (OAuth authorization_code) flow.

Onboard autonomously — create your own account & credentials

An agent can provision its own machine credentials with no human UI, using the control-plane and OAuth client_credentials grant. Four calls:

Create an account (email + a password of 10+ characters you generate and keep; next time, /console/sign-in with the same pair).

curl -X POST https://api.realityping.com/api/v1/console/sign-up \
  -H "Content-Type: application/json" \
  -d '{"email":"agent@yourdomain.tld","password":"<generated, 10+ chars>"}'
# → { "session_token": "...", "user": { "email_verified": false } }
# The sandbox works at once. Billing for real missions waits until a human
# clicks the confirmation link sent to that email.

Create a machine OAuth client (with the scopes your agent needs).

curl -X POST https://api.realityping.com/api/v1/console/oauth-clients \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent","scopes":["quotes:read","missions:create","missions:read"]}'
# → { "client": { "client_id": "..." }, "client_secret": "..." }

Get a machine access token (no user, no consent).

curl -X POST https://api.realityping.com/api/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "resource=https://api.realityping.com/api/v1/mcp"
# → { "access_token": "rly_oat_...", "token_type": "Bearer", ... }

Call the service over MCP (or REST) with that token.

curl -X POST https://api.realityping.com/api/v1/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
        "name":"reality_get_quote",
        "arguments":{"location":{"sandbox_alias":"REALITY_SANDBOX_PARIS_STORE"},
                     "mission_type":"VERIFY_BUSINESS_OPEN"}}}'

Prefer the standard MCP path? Add the bare MCP URL to your host: it gets a 401 pointing at the protected-resource metadata, can self-register via Dynamic Client Registration (RFC 7591) at POST /api/v1/oauth/register, and complete OAuth 2.1. See discovery below.

OAuth 2.1 discovery

Purpose	URL
Protected-resource metadata (MCP)	`/.well-known/oauth-protected-resource/api/v1/mcp`
Authorization-server metadata	`/.well-known/oauth-authorization-server`
Dynamic Client Registration	`POST /api/v1/oauth/register`
Token	`POST /api/v1/oauth/token`

Scopes: quotes:read, missions:create, missions:read, missions:cancel, evidence:read, billing:read, webhooks:manage. Tokens are audience-bound to the resource you request. A per-mission spend cap is satisfied programmatically (declare a budget) — it is a policy, not a UI gate.

Sandbox quickstart (no signup)

To try the loop immediately, use the built-in sandbox API key rly_test_sandbox as a Bearer token, and the sandbox place alias REALITY_SANDBOX_PARIS_STORE with mission type VERIFY_BUSINESS_OPEN.

Paying and invoices