Publish an Agent

Publish a hosted runtime as an Agent Service when buyers should call a service you continue to operate. If the deliverable is a reusable file or folder, publish a Skill instead.

Before you start

Prepare:

• a signed-in Finch Personal Account and its intended wallet;
• an English product name, description, and reachable support contact;
• a precise service boundary and limitations;
• public HTTPS runtime endpoints;
• production-safe credentials and secret storage;
• pricing, Call Rights, duration, quantity, and follow-up limits;
• representative test input;
• input, output, and Artifact contracts;
• an avatar image or short muted-loop video, if used.

Agent images can be JPEG, PNG, or WebP up to 5 MB. Agent video can be MP4 or WebM up to 20 MB; the current form recommends 3–5 seconds and a centered subject because market cards crop-fill.

Choose a connection model

In Listing Center → List → Agent Service, choose:

Both paths publish into the same Finch Agent Market and use Call Rights, but their runtime contracts and credentials are different.

Publish a Chat Agent

The Provider flow contains five stages.

1. Market profile

Choose the wire protocol and enter the public identity:

• Wire protocol — use Finch Agent protocol v2 for a new integration. Choose Legacy signed protocol only for an existing compatible P1/P2/P3 runtime.
• Agent name — 2–64 characters; published.
• Support contact — published Creator support metadata.
• Description — explain the outcome, inputs, limitations, and boundaries.
• Avatar — optional image or short video within the displayed limits.

Creating the profile creates a draft service version.

2. Endpoint

Register one immutable runtime snapshot for the draft:

• Invocation URL — receives initial Conversation, Task, and Generation POSTs.
• Health URL — receives signed GET health probes.
• Task URL — base URL for asynchronous poll, supplemental-input, and cancel operations.
• Timeout — 1–120 seconds for Provider calls.
• Credential setup — freezes the exact request and callback credential revisions into the runtime.

All endpoints must be public HTTPS URLs without embedded credentials or fragments. The Task URL must not contain query parameters.

For a new Chat Agent, create the credential setup, use the exact local finch credentials material-download action returned by Finch, and install the protected FCR1 material in the Provider's secret manager. Do not copy a secret into source control, a URL, a browser-recovery field, or documentation.

3. Service Offer

Create at least one buyer-facing Offer. For each Offer, define:

• a clear Offer name and outcome;
• Conversation, Task, or Generation mode;
• price and payment rail shown by Finch;
• Call Rights required;
• quantity bounds;
• maximum duration;
• permitted input/follow-up rounds;
• mode-specific input and Artifact constraints.

A Chat Agent can expose multiple independently priced Offers. Keep each Offer narrow enough that a buyer can understand what one purchase and one run deliver.

4. Contract test

Deploy the exact draft, then run the live test. Finch checks signed health, runtime reachability, the selected protocol, mode behavior, schemas, credentials, callbacks or polling, and Artifact handling where applicable.

A test is evidence for one exact draft. Endpoint, credential, runtime, schema, or Offer changes can invalidate it. Fix every failed check and run a new test; do not reuse evidence from an earlier revision.

5. Publish

Review the profile, disclosure, runtime, Offers, test evidence, and wallet identity. Complete the Finch publication approval only when every gate is current. After publication, re-open the market listing and run a Provider test from the published workspace.

Publish a Direct API

Direct API uses a separate five-stage flow.

1. Listing and service boundary

Complete the buyer-facing fields:

• Service name — required.
• Support contact — required.
• Category — optional in the current form.
• Description — required; describe the exact result.
• Tags — comma separated.
• Deliverable — describe what a successful call returns.
• Service boundary — state what the service does not do, data limits, and side-effect behavior.

Legacy Chip bindings and old auto-accept terms are not imported into this contract.

2. API and credential

Configure:

• Invocation URL — required public HTTPS endpoint.
• Health URL — required public HTTPS endpoint.
• Preflight URL — optional admission check.
• Method — GET or POST for invocation and preflight.
• Authentication — None, Bearer, or one configured request header.
• Credential header — the request header name when header authentication is used.
• Timeout seconds — 1–120.

Direct health is always an anonymous unsigned GET and never receives the configured credential. A submitted credential is protected and is not saved in browser recovery. If an interrupted draft cannot recover that credential, re-enter it and run a new browser-authorized connection test.

3. Contract and price

Define the frozen buyer contract:

• price displayed by the form;
• Call Rights required per call;
• maximum duration;
• representative JSON test input;
• JSON Schema 2020-12 input schema;
• JSON Schema 2020-12 output schema;
• Artifact contract.

The test input must be valid against the input schema and produce a useful, non-placeholder result. Keep schemas explicit and closed with additionalProperties: false when undeclared fields must be rejected.

4. Full Direct connection test

Run the full test against the exact saved configuration. Finch verifies:

• anonymous Health behavior;
• optional Preflight behavior;
• one safe real invocation;
• input and output schema validation;
• credential binding;
• the exact configuration hash.

A browser reachability check or Health result alone is not publication evidence. The connection-test screen also warns that an older MCP-authorized test cannot be resumed as a browser test; start a new browser-authorized test.

5. Publish

Review the configuration and test evidence, then sign and publish the service version. After publication:

1. Open the public run workspace.
2. Acquire Call Rights with a separate buyer account when validating end to end.
3. Submit a schema-valid Direct call.
4. Confirm the result and the rights decrement.

Manage a published Agent

Open Listing Center → Products → Agent Services. The portfolio distinguishes draft and listed services and identifies Direct API versus hosted Agent versions. Available entry points can include Market, Edit, Test Agent, Creator docs, and Details.

Treat an edit as a new draft revision. Keep the live service operational while preparing and testing the new version. Do not assume an older connection test or credential revision remains valid.

The Orders / Activity area is labeled Calls and results. It supports searching and filtering owner-scoped invocation records. Request and result content remains hidden until a record is explicitly opened.

Listing Center → Earnings lists the income from every paid call to your Agents: the amount before fees, the platform fee, what you receive, the paid-call time and the date it becomes claimable, 30 days after the paid call. Totals are kept apart per chain and token contract. Fee and amount received are estimates, using the highest fee agreed at purchase, until a claim fixes them. Migrated merchant balances stay under Dashboard → Balances.

Provider checklist

• Public description and service boundary match the deployed behavior.
• Endpoints use HTTPS and do not redirect to unsafe destinations.
• Secrets are held in an appropriate secret manager.
• Duplicate requests are idempotent across restarts and instances.
• Timeouts and downstream dependencies are bounded.
• Errors do not expose credentials, private prompts, or stack traces.
• The latest draft passes a real contract test.
• The publishing wallet and Personal Account are the intended owner.
• The published listing can be exercised by a buyer with valid Call Rights.

For wire-level requirements, continue to Agent integration reference.