External x402 Sources for Agent Discovery

External x402 sources widen the set of paid endpoints an agent can find. The useful question is not whether a source returned a match, but what the discovery client can safely conclude from that record before it sends a request or compares the provider with another offer.

A source sweep is a recall mechanism. It reaches resource catalogues beyond one reviewed marketplace and brings back possible providers. That breadth matters for a provider that wants to be found, but only if the result keeps its provenance, freshness and evidence limits attached.

Read each source as a stream of claims

An x402 discovery record can carry a resource URL, a description, a protocol version, accepted payment requirements, extension metadata and a last-updated value. Discovery APIs may also expose filters and pagination. Those fields make the record searchable and retrievable. They do not show that a second system has executed the endpoint or verified every declared term.

The collector should therefore preserve what the source actually returned. A useful ingestion record includes:

• The source name and source record identifier, when one exists.
• The resource URL and advertised HTTP method.
• The x402 protocol version and declared payment requirement block.
• The capability description and input or output metadata supplied by the source.
• The source's last-updated value and the time the collector fetched it.
• The raw source status, including missing or malformed fields.
• The page, cursor or offset that produced the record for repeatable collection.

This is the machine-readable equivalent of keeping a citation. If the description changes tomorrow, the buyer should be able to tell whether the provider changed its listing, the source refreshed its cache or the aggregator rewrote the record.

Providers can make this easier by publishing a stable resource identity and a bounded job description. The practical fields in a crawler-readable API catalogue matter more than a broad marketing category because an agent needs to match a task to an executable route.

Sweep completely, then expose freshness

A catalogue query is not complete just because its first response contains relevant items. External sources can paginate their resource lists and offer filters for resource type, recipient, scheme, network or extension data. A collector must follow the source's pagination contract and record when the sweep ended.

Freshness needs two timestamps. The source's update time describes what the source claims about the record. The collection time describes when the aggregator last observed that claim. Neither should silently replace the other.

When a source times out or returns an invalid page, keep the last known record only if its age remains visible. Do not present a partial sweep as a complete view of the wider x402 web. The client can still return useful results, but it should also return the sources queried, the sources that failed and the observation time.

This makes absence interpretable. An endpoint missing from one sweep may have been removed, may sit on an uncollected page or may belong to a source that was unavailable. “Not found in this run” is narrower and more honest than “does not exist.”

Deduplicate identities without erasing conflicts

The same endpoint can appear in several external x402 sources. Simple URL equality catches some duplicates, but aggressive merging creates a different problem. Two records may share a hostname while describing different methods, paths, input contracts or charging units.

Normalize only the parts that have unambiguous syntax, such as URL casing rules and removable fragments. Then compare the complete resource identity: scheme, host, path, method, protocol version and request contract. Keep source-specific values beside the normalized key.

If two sources disagree, surface the disagreement. A later update time does not automatically make one description correct. Payment terms in particular can drift, so a collector should not manufacture a single current price, asset or rail from conflicting cached records. The live resource response remains the place to inspect the payment terms the endpoint currently returns.

This approach is different from treating every external listing as a trusted catalog row. The boundary between reviewed and unreviewed listings remains intact even after duplicates are grouped.

Give the agent an explicit next action

An external hit should tell the agent what it may do next. It can inspect the advertised capability, fetch the resource contract, compare source records or send the provider into a review workflow. It cannot silently place the record into a scored candidate set.

In Apiosk, reviewed catalogue results receive a stable `candidate_id`. That identifier can continue into `GET /v1/compare?candidates={id},{id}` and `GET /v1/decide?candidates={id},{id}`. External results appear separately in `external_candidates` without a `candidate_id`. They are unreviewed, unmeasured and not settleable through Apiosk.

The distinction prevents three unsafe shortcuts. An external description does not prove input compatibility. Advertised payment metadata does not become an Apiosk-normalized price. A source update time does not become measured latency or success rate. Result quality and provider terms are not measured by Apiosk either.

For an automated buyer, the safe actions are concrete:

• Continue with reviewed candidates when the workflow requires comparison or settlement through Apiosk.
• Show external hits as leads with source and freshness metadata attached.
• Inspect an external resource separately when broader coverage matters more than immediate automation.
• Ask the provider to enter review when the endpoint should become comparable and selectable.

The larger agent API discovery path can include both sets without pretending they carry the same evidence.

Providers should publish for ingestion, not just display

A provider cannot control every external index, but it can reduce ambiguity at the source. Keep the resource URL stable. Name one bounded capability. Publish the method, required inputs and successful output boundary. Use the correct discovery metadata for the x402 version the endpoint serves, and test that the chosen discovery surface actually returns the record.

Do not assume successful settlement proves successful indexing. Discovery metadata and payment execution have different jobs. A route can accept payment while remaining hard to find because its description, schema or version-specific discovery declaration is incomplete.

The checklist for listing an API in an x402 directory covers the fields that turn a URL into a callable offer. Consistency across the live endpoint, discovery record and provider documentation gives collectors fewer conflicts to preserve.

Where Apiosk fits

`GET /v1/discover?q=…` searches the reviewed Apiosk catalogue and can sweep external x402 sources. It returns reviewed candidates with stable identifiers and external matches in a separate block. That gives the agent broader coverage while keeping the downstream contract strict.

Reviewed candidates can move into comparison and decision. External matches cannot. They remain leads until their identity, inputs, payment terms and operating evidence have entered the reviewed path. Providers that want that transition can list an API for review with a precise capability and request contract.

Apiosk does not turn source count into trust. It uses the external sweep to show what else may exist, preserves the boundary around what has not been established and lets the buyer decide whether separate inspection is worth the work.