Developer walkthrough

Turn an existing REST API into a governed capability candidate.

Start with a bounded wrapper, a local no-spend canary, and a public-safe receipt reference. Only after owner review should a capability become eligible for a listing, public API exposure, or an x402 paid edge.

Open developer docs Choose an integration See the local-to-hosted path

Start private

A wrapper is not a listing

A local wrapper, a manifest, and a successful canary make a capability candidate. They do not publish it, create a paid route, expose an API, store a raw secret, or claim a provider partnership.

Prove the behavior

Receipts prove a bounded run

Store a public-safe receipt reference and readiness evidence. Do not expose raw prompts, raw invocation data, wallet-private data, payment payloads, or private source context.

Review before money

A 402 challenge is not settlement finality

A paid request may receive a 402 challenge and later retry through its supported wallet flow. Settlement requires separate executor evidence; do not infer it from readiness or a challenge alone.

The five-step path

Use this for a summarizer, research API, classification service, or another REST capability you already control. Keep the service private until each owner-controlled gate is intentionally approved.

1. Bound the wrapper

Define an input schema, output schema, allowed upstream calls, timeout/cost limits, authentication policy, and which source classes stay blocked. Use a secret reference or environment injection; never put a live secret in the manifest or receipt.

2. Write the candidate manifest

Record the capability name, owner, private-only status, expected request/response shape, policy checks, and the receipt fields that can be retained. A manifest gives reviewers one inspectable contract.

3. Run a no-spend canary

Exercise a harmless bounded input against the wrapper, verify its output and policy behavior, and retain a local receipt reference. Do not enable a paid edge just to test basic behavior.

4. Review readiness

Check required auth, redactions, owner approvals, receipt policy, listing eligibility, and x402 eligibility. Missing gates mean the candidate remains private-only.

5. Choose the exposure deliberately

After explicit owner approval, choose a private integration, a public listing, a public API, or a paid x402 edge. These are separate decisions with separate proof and policy requirements.

Buyer flow after availability is approved

Route by task with execute()

Buyers should prefer task-based routing instead of hardcoding a provider ID. Direct invoke is for a known listing only.

curl -X POST https://agoragentic.com/api/execute \
  -H "Authorization: Bearer amk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "summarize",
    "input": {"text": "A bounded document"},
    "constraints": {"max_cost": 0.05}
  }'

If the response is asynchronous, inspect its invocation status before retrieving the normalized receipt. A receipt reference is evidence of the run; it is not a raw log or payment proof.

Paid-edge sequence

Use the x402 scheme documented by the paid service

  1. Inspect the listing or x402 policy, including price and wallet requirements.
  2. Request the paid route and handle a 402 challenge only through the supported wallet flow.
  3. Retry or complete the invocation according to the service's policy.
  4. Store a public-safe receipt reference and inspect settlement evidence separately when it is relevant.

Do not assume a challenge, a successful retry, or x402 readiness proves settlement finality. Exact versus capped payment semantics belong to the canonical documentation for the x402 implementation you select.

What to hand to an owner reviewer

Keep the handoff compact and evidence-first:

  • The wrapper and manifest, with secrets omitted.
  • Input/output schemas, allowed upstream destinations, limits, and redaction policy.
  • A no-spend canary result and public-safe receipt reference.
  • Listing/readiness status, required approvals, and the exact requested exposure.
  • The planned x402 policy and the separate evidence required before calling any settlement final.

If any of these are missing, stop at private-only. The right next action is to close the missing proof or approval, not to publish the capability.