# agentic-endpoints

> Pay-per-call HTTP utilities for autonomous AI agents. There is no
> signup, no API key and no invoice. Every paid endpoint answers 402
> with a price; you sign a stablecoin payment and retry.

## How to pay

Three options, and the same endpoints accept all of them:

0. **Try it free first.** POST to /credits/trial. You get a $0.10 credit
   token back immediately — no account, no email, no wallet, no approval
   step. That is roughly 10 calls. Send it as `X-Credit-Token` exactly
   like a bought one. One allowance per client address: asking again
   returns the same token and whatever balance is left, so it is safe to
   retry but it will not top you up.
1. **Per call (x402).** Send the request. You get HTTP 402 with a
   `payment-required` header holding a base64 challenge that names the
   amount, the asset (USDC on Base, chain `eip155:8453`) and the
   recipient. Sign an EIP-3009 authorization and retry with an
   `X-PAYMENT` header. Any x402 client library does this for you.
2. **Prepaid credits.** POST to /credits/buy ($5 buys $6.00) or
   /credits/buy-25 ($25 buys $32.50). You get a token back once, and
   only once. Send it as `X-Credit-Token` on any paid endpoint and the
   list price is debited from your balance with no per-call signature.

## Agent-to-agent (A2A)

This service is also an A2A agent. The card is at
/.well-known/agent-card.json (protocol 0.3, JSONRPC) and the transport
is POST /a2a.

Every paid endpoint above is an A2A skill, which is unusual: A2A has no
payment step, so paid agents normally expose only their free operations
there. Here the credit token does the job — send `X-Credit-Token` on the
/a2a request and the skill runs in one round trip. Combined with the free
trial above, an A2A client needs no wallet at all to start.

Name the skill in `message.metadata.skill`, or send a DataPart shaped
`{ skill, input }`. Skill ids are the route path without the leading
slash, with slashes replaced by dots: /once-key/complete is
`once-key.complete`. `skills/list` returns them all over JSON-RPC.

Results come back as a Message whose DataPart is exactly the JSON the
HTTP route would have returned. No Tasks are created, so `tasks/get`
always reports not-found, and streaming is not offered.

### Concurrency

Paid calls issued concurrently from the same wallet are refused a
noticeable fraction of the time. The facilitator will not verify
overlapping authorizations from one payer, and you get an ordinary 402.

A 402 means the payment did NOT happen and you were NOT charged: any
status at or above 400 cancels settlement. Retrying with a fresh
signature is safe and will not double-spend. Issue paid calls
sequentially, or retry on 402 with a short backoff. Prepaid credits
avoid this entirely, since they carry no per-call signature to verify.

## Endpoints

### POST /once-key — $0.010

Atomic idempotency witness — claim an action exactly once, record its result, and replay that result to every later caller

Request:
```json
{
  "namespace": "invoices-4f9c2b1e8d7a",
  "action_key": "charge-order-1042",
  "ttl": 86400,
  "lease_ttl": 300
}
```

### POST /scrape — $0.010

Web scraping and text extraction

Request:
```json
{
  "url": "https://example.com",
  "format": "text"
}
```

### POST /pdf-parse — $0.020

PDF text extraction

Request:
```json
{
  "url": "https://example.com/report.pdf"
}
```

### POST /compress — $0.010

Token compression for LLMs

Request:
```json
{
  "text": "Long input text to be compressed before it is sent to a model.",
  "target_tokens": 100,
  "strategy": "extractive"
}
```

### POST /vault/store — $0.02

Store an encrypted item in the vault. The first store claims the namespace and returns a one-time namespace_token.

Request:
```json
{
  "namespace": "agent-secrets-4f9c2b1e8d7a",
  "key": "openai-api-key",
  "ciphertext": "base64-of-your-client-side-encrypted-bytes",
  "alg": "AES-GCM",
  "ttl": 604800
}
```

### POST /vault/delete — $0.005

Delete an item from the vault (requires the namespace_token)

Request:
```json
{
  "namespace": "agent-secrets-4f9c2b1e8d7a",
  "key": "openai-api-key",
  "namespace_token": "the token returned by your first store"
}
```

### POST /credits/buy — $5.00

Buy $6.00 of prepaid credit for $5.00 (20% bonus). Returns a credit token; send it as X-Credit-Token on any paid endpoint to be debited at list price with no per-call payment signature.

### POST /credits/buy-25 — $25.00

Buy $32.50 of prepaid credit for $25.00 (30% bonus). Returns a credit token; send it as X-Credit-Token on any paid endpoint to be debited at list price with no per-call payment signature.

### POST /meetings/import — $0.010

Import a meeting transcript. Accepts a raw WebVTT or SRT export straight from Zoom, Teams, Meet or a notetaker -- timestamps and cue numbering are stripped so search matches phrases the export split across cues. visibility "private" stores ciphertext this service cannot read; "queryable" stores plaintext and indexes it for search. The first import claims the namespace and returns a one-time namespace_token.

Request:
```json
{
  "namespace": "my-meetings-4f9c2b1e8d7a",
  "title": "Pricing review",
  "occurred_at": "2026-01-04T15:00:00.000Z",
  "source": "webvtt",
  "visibility": "queryable",
  "transcript": "Alice: we agreed to ship the redesign before the audit...",
  "participants": [
    "Alice",
    "Bob"
  ]
}
```

### POST /meetings/search — $0.010

Full-text search across your queryable meetings. Returns ranked excerpts, and reports how many meetings were private and therefore not searched.

Request:
```json
{
  "namespace": "my-meetings-4f9c2b1e8d7a",
  "namespace_token": "the token returned by your first import",
  "query": "pricing",
  "limit": 10
}
```

### POST /x402/verify — $0.010

Before paying a stranger's x402 endpoint, read its live payment challenge and compare it against every previous observation. Flags a changed receiving address, network or asset as critical drift. Reports what the endpoint declares; it does not certify the operator.

Request:
```json
{
  "url": "https://example.com/api/thing",
  "expect": {
    "pay_to": "0x...",
    "max_price_usd": 0.01
  }
}
```

### POST /reach — $0.010

Can agents reach this URL? Sends one GET as each of nine common clients (curl, node, Python urllib, Python requests, libwww-perl, a browser, GPTBot, ClaudeBot, Googlebot) and reports which are refused and why, plus robots.txt AI-crawler blocks, /llms.txt and the http-to-https redirect. Read-only.

Request:
```json
{
  "url": "https://example.com/"
}
```

### POST /reach/report — $69.00

Full reachability report for one site, up to 20 pages: every page checked from nine common clients, the likely cause of each refusal (Cloudflare 1010, firewall rule, bot challenge, origin server, AI-crawler block, POST-dropping redirect, missing llms.txt) with the exact fix and a curl that reproduces it, a prioritised fix list, a private report page, and 3 free re-scans within 30 days compared before and after.

Request:
```json
{
  "urls": [
    "https://example.com/",
    "https://example.com/api/door"
  ]
}
```

### POST /meetings/summarize — $0.050

Ask a question in plain language and get an answer grounded in your own meetings, with a citation to the meeting each claim came from. Retrieves the relevant transcripts and reasons over them. When nothing matches, no answer is generated rather than one being invented.

Request:
```json
{
  "namespace": "my-meetings-4f9c2b1e8d7a",
  "namespace_token": "the token returned by your first import",
  "question": "what did we decide about pricing?",
  "limit": 5
}
```

### POST /meetings/get — $0.005

Fetch one meeting in full, by meeting_id (requires the namespace_token)

Request:
```json
{
  "namespace": "my-meetings-4f9c2b1e8d7a",
  "namespace_token": "the token returned by your first import",
  "meeting_id": "6f1c3b90-0f6a-4c2e-9a1e-2b7d5c8e4a11"
}
```

### POST /meetings/list — $0.005

List the meetings in a namespace with their metadata, newest first. Never returns transcripts (requires the namespace_token)

Request:
```json
{
  "namespace": "my-meetings-4f9c2b1e8d7a",
  "namespace_token": "the token returned by your first import"
}
```

### POST /meetings/delete — $0.001

Delete a meeting and remove it from the search index (requires the namespace_token)

Request:
```json
{
  "namespace": "my-meetings-4f9c2b1e8d7a",
  "namespace_token": "the token returned by your first import",
  "meeting_id": "6f1c3b90-0f6a-4c2e-9a1e-2b7d5c8e4a11"
}
```

### POST /vault/list — $0.005

List the keys held in a vault namespace with their metadata, without returning any ciphertext (requires the namespace_token)

Request:
```json
{
  "namespace": "agent-secrets-4f9c2b1e8d7a",
  "namespace_token": "the token returned by your first store"
}
```

### POST /vault/exists — $0.005

Check whether a key exists in the vault without returning its ciphertext (requires the namespace_token)

Request:
```json
{
  "namespace": "agent-secrets-4f9c2b1e8d7a",
  "key": "openai-api-key",
  "namespace_token": "the token returned by your first store"
}
```

### POST /vault/retrieve — $0.02

Retrieve an encrypted item from the vault (requires the namespace_token issued at claim time)

Request:
```json
{
  "namespace": "agent-secrets-4f9c2b1e8d7a",
  "key": "openai-api-key",
  "namespace_token": "the token returned by your first store"
}
```

## Exactly-once workflow

`/once-key` is the endpoint you cannot replace with a library,
because it answers a question no single agent can answer alone:
has anyone, anywhere, already done this? Use it like this:

1. `POST /once-key` with your `action_key` and a `lease_ttl`.
   - `claimed` — you won. Do the work.
   - `in_progress` — someone else is doing it. Wait
     `retry_after` seconds; do not start the work.
   - `duplicate` — already done. The `result` field holds the
     original outcome; use it and do not repeat the work.
     `has_result` is false if no result was ever recorded, so
     a null result is never mistaken for a lost one. If
     `result_error` is present the stored result could not be
     read back: the work DID run, so do not repeat it, but the
     recorded outcome is lost.
   - `held` — someone else claimed it but has not finished and
     set no lease. There is no result and may never be one. Do
     NOT treat this as done and do NOT do the work; the key is
     locked until `expires_at`.
   - `conflict` — same key, different payload hash. Your key
     derivation is wrong; do not proceed.
2. `POST /once-key/complete` with the `result`. Free. This is
   what lets every later caller learn the outcome.
3. If the work failed, `POST /once-key/release`. Free. The key
   becomes immediately retryable.

If you pass `lease_ttl` and then crash, the claim is released
automatically once the lease lapses and the next caller takes
it over with `recovered: true`. Without `lease_ttl` a claim is
held until its full `ttl`, which is the safer default: nothing
can ever run your side effect twice.

## Free endpoints

- `GET https://testnet.agentic-endpoints.com/` — this catalogue as JSON
- `GET https://testnet.agentic-endpoints.com/health` — liveness
- `GET https://testnet.agentic-endpoints.com/stats` — usage counts, published openly so you
  can tell a maintained service from an abandoned one
- `GET https://testnet.agentic-endpoints.com/status` — uptime, error rate and latency, derived from this service's own cron ticks and request log, so you can judge
  whether it is safe to route paid work through
- `GET https://testnet.agentic-endpoints.com/openapi.json` — OpenAPI 3.1 description
- `POST https://testnet.agentic-endpoints.com/once-key/complete` — Record the outcome of a claimed action_key
- `POST https://testnet.agentic-endpoints.com/vault/rotate-token` — Replace a vault namespace token
- `POST https://testnet.agentic-endpoints.com/once-key/release` — Surrender a claim whose work failed
- `POST https://testnet.agentic-endpoints.com/credits/trial` — Get a free evaluation credit, no account required
- `POST https://testnet.agentic-endpoints.com/credits/balance` — Check a prepaid credit balance
- `https://testnet.agentic-endpoints.com/mcp` — Model Context Protocol server (JSON-RPC)