AIMarket Playground

Back to provider connection

AIMARKET-PROVIDER-INVOKE/1

Provider setup guide

Check your own endpoint with one real invocation and a request-bound Ed25519 signature. The check does not require a Hub token, stake, account or payment channel.

1. Prepare a test provider

Use harmless input and a test deployment: your provider's own execution can cost money or have side effects. The header X-AIMarket-Test-Mode: provider-invoke-v1 identifies the check, but does not authorize the caller or make a call free.

Configure capability.json with product_id, capability_id, publisher_id, name, invoke_url, provider_pubkey, price_per_call_usd, input_schema and output_schema. The public URL must use HTTPS on port 443; the key must be a base64-encoded 32-byte Ed25519 public key.

2. Confirm endpoint control

  1. Open Connect your provider, import the manifest and enter a JSON test input matching its schema.
  2. Authorize the test call and select Prepare connection.
  3. Download the proof and serve that JSON at the displayed address on your provider's origin:
.well-known/aimarket-provider-check.jsonJSON
https://your-provider.example/.well-known/aimarket-provider-check.json

{"challenge":"<64-character token issued by Playground>"}

Serve the response as application/json without compression or redirects. The challenge is bound to this browser session, manifest and input; it expires after 15 minutes. There are up to three ownership attempts.

Providers generated from the updated Python or TypeScript templates expose this route when AIMARKET_ONBOARDING_CHALLENGE contains the issued token. Set the variable and restart the provider; remove it after checking. Older or custom providers can serve the proof as a static JSON file at the same address.

3. Run the check

Select Verify & invoke. Playground verifies the proof, makes one POST, checks the output schema and verifies X-Provider-Signature. Download the report with the signed envelope and public key.

A repeated request with the same challenge retrieves the cached result, including failures after dispatch. It does not invoke again. A new challenge authorizes a new call. Reports expire after 15 minutes and are lost on server restart.

Local checks and CI

The CLI is available from the updated Playground source checkout. Do not assume this new command is already published on PyPI. Create a JSON input file such as {} for an unchanged generated provider, start the provider, then run:

aimarket-provider-checkCLI
cd aimarket-playground
uv sync --extra dev
uv run aimarket-provider-check ../my-agent/capability.json \
  --input ../my-agent/test-input.json --allow-loopback > report.json

Exit code 0 means pass; 1 means failure. Archive the report even on failure. The CLI performs the same invoke, schema and signature checks; it does not claim endpoint ownership. --allow-loopback permits local development only, not arbitrary private networks. Reports contain provider results: use non-sensitive fixtures.

The signature contract

Ed25519JSON
{
  "capability_id": "my-agent.invoke@v1",
  "product_id": "my-agent",
  "input_sha256": "<SHA-256 of canonical input JSON>",
  "result": {}
}

Canonical JSON uses sorted keys, compact separators and UTF-8 with unescaped Unicode. The provider signs these bytes with Ed25519. For Python/TypeScript interoperability, use integers in signed data: the existing contract does not normalize 1.0 and 1 across languages.

Limits and scope

JSON is limited to 64 KiB, depth 16 and 4096 nodes. Duplicate keys, non-finite numbers, malformed UTF-8, private network destinations, redirects and compressed responses are rejected. Proof and invoke use the same validated IP and TLS hostname.

Supported JSON Schema 2020-12 keywords:

$schema title description type properties required additionalProperties items enum const minimum maximum exclusiveMinimum exclusiveMaximum minLength maxLength minItems maxItems minProperties maxProperties

Other keywords, including references, regular expressions and schema composition, fail explicitly. The service allows four concurrent checks and up to 250 stored challenges. Hourly limits shared by preparation and uncached attempts: 20 per visitor, 60 per source IP and 500 per process. Deployment uses one ASGI worker, with rate limiting and trusted proxy configuration at the edge.

A pass applies to one provider invocation. This is not whole-protocol certification, Hub publication or proof of provider identity. Hub receipts, payments, discovery, federation, replay detection and load are not tested. The report itself is not signed by the Hub; its timestamp is not attested by the provider. Identical inputs and results can produce identical signatures, so freshness is not proven.

Connect your provider