Bazaar discovery

Make your API discoverable to every AI agent on the internet, automatically. When you accept payments through Kobaru Gateway, your API is automatically listed in a public marketplace where AI agents and developers can find, understand, and pay for your service -- no manual submission required.

Why discovery matters

APIs behind paywalls are invisible to the broader ecosystem. An AI agent searching for a weather API, a translation service, or a document parser has no reliable way to find yours unless it already knows the URL.

Bazaar discovery solves this. It creates a public, machine-readable catalog of all APIs that accept x402 payments through Kobaru. When you include a small metadata extension in your payment configuration, your API appears in this catalog with its description, pricing, input/output schemas, and provider information.

The result: your API becomes findable by any AI agent or developer querying the discovery endpoint, without you lifting a finger beyond the initial setup.

How it works

Discovery is a fire-and-forget process built into the payment verification flow. There are no extra API calls, no dashboards to manage, and no forms to fill out.

You configure your API with the bazaar extension in your x402 payment middleware. This extension contains metadata about your API: its title, description, schemas, and your provider information.

A client makes a payment request. When Kobaru verifies the payment, it automatically extracts the bazaar extension metadata from the request.

Your API is listed immediately. The extracted metadata is stored and made available through the public discovery endpoint. If your API was already listed, the metadata is updated.

AI agents and developers find your API. Anyone can query the discovery endpoint to browse available services, filter by type or category, and get the pricing and schema information they need to call your API.

This entire process adds zero latency to payment verification. The discovery registration happens asynchronously in the background, and if it fails for any reason, it does not affect the payment flow.

Key point: Discovery registration happens on every payment verification. This means your listing stays current automatically. If you change your pricing, description, or schemas, the listing updates the next time a client pays.

Key benefits

Zero-effort listing

You do not need to create an account on a marketplace, fill out forms, or submit your API for review. Include the bazaar extension in your payment configuration, and discovery happens automatically.

Global visibility

Your API becomes visible to any AI agent, developer tool, or application that queries the discovery endpoint. There is no geographic restriction and no authentication required to browse the catalog.

Rich metadata for AI agents

The discovery response includes structured input and output schemas that AI agents can parse programmatically. An agent does not need to guess your API's request format -- it reads the schema and constructs the correct call automatically.

Automatic updates

Every payment verification refreshes your listing. Change your price, update your description, or add new schemas -- the catalog reflects the latest version without any manual action.

Provider trust signals

Include your organization name, description, and website in the bazaar extension. This information appears alongside your API listing, helping consumers evaluate credibility before making a purchase. Provider information is available for registered merchants.

Industry-standard protocol

Bazaar discovery follows the x402 v2 specification. Your listing is compatible with the broader x402 ecosystem, making your API discoverable across any facilitator that supports the standard.

What makes Kobaru's discovery different

Kobaru's implementation goes beyond the baseline x402 bazaar specification with features that improve discoverability, AI compatibility, and developer experience.

Feature	Description
Provider information	Your organization details appear as a dedicated top-level field, making it easy for consumers to identify who built the API
Top-level HTTP method	The HTTP method (GET, POST, etc.) is exposed at the resource level for immediate visibility, not buried inside nested schemas
Schema enrichment	Each payment option includes a description, MIME type, structured input/output schema, and pricing metadata
Automatic registration	APIs are registered from payment requests with zero manual intervention
Full x402 v2 compliance	Response format follows the industry standard, ensuring compatibility across the ecosystem

Discovery endpoint

AI agents and developers discover your API through a single public endpoint:

GET https://gateway.kobaru.io/discovery/resources

This endpoint requires no authentication. Anyone can query it to browse available services.

Query parameters

Parameter	Type	Default	Description
`type`	string	all	Filter by resource type: `http`, `websocket`, or `grpc`
`tags`	string	all	Filter by tags (comma-separated, AND logic - resource must have ALL specified tags)
`limit`	number	20	Results per page (1--100)
`offset`	number	0	Pagination offset

Example request

Rate limiting

The discovery endpoint allows 60 requests per minute per IP address. This is sufficient for periodic polling or on-demand lookups, and prevents abuse of the public catalog.

Bazaar extension fields

The bazaar extension is a JSON object you include in your x402 payment configuration under extensions.bazaar. It contains an info field with your API metadata.

The `info` field

This is where you describe your API. All sub-fields are optional, but providing more detail improves discoverability and AI agent compatibility.

SDK limitation & storage: The standard SDK's declareDiscoveryExtension() doesn't expose parameters for tags, title, and provider. Use manual construction or our helper function to include these fields. Additionally, Kobaru stores them only for registered accounts (spam prevention). Schemas, pricing, and descriptions work for everyone.

{
  "extensions": {
    "bazaar": {
      "info": {
        "title": "Real-time Weather API",
        "description": "Get current weather conditions for any location worldwide",
        "method": "GET",
        "input": {
          "type": "application/json",
          "schema": {
            "properties": {
              "location": {
                "type": "string",
                "description": "City name or coordinates"
              }
            }
          }
        },
        "output": {
          "type": "application/json",
          "schema": {
            "properties": {
              "temperature": { "type": "number" },
              "conditions": { "type": "string" },
              "humidity": { "type": "number" }
            }
          }
        },
        "provider": {
          "name": "WeatherCo",
          "description": "Leading weather data provider",
          "url": "https://weatherco.example.com",
          "contact": "api@weatherco.example.com"
        },
        "tags": ["weather", "data", "real-time"],
        "pricing": {
          "model": "pay_per_request",
          "amount": "1000",
          "asset": "USDC"
        }
      }
    }
  }
}

Info field reference

Field	Type	Description
`title`	string	A short, descriptive name for your API endpoint. SDK limitation: Use manual construction or helper. Stored only for registered accounts.
`description`	string	What your API does, in one or two sentences
`method`	string	HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, or `OPTIONS`
`input`	object	Request format: `type` (MIME type) and `schema` (JSON Schema for parameters)
`output`	object	Response format: `type` (MIME type) and `schema` (JSON Schema for the response body)
`provider`	object	Your organization: `name`, `description`, `url`, and `contact`. SDK limitation: Use manual construction or helper. Stored only for registered accounts.
`tags`	string[]	Categories and keywords for filtering. Use 2-5 specific, lowercase tags (e.g., `["ai", "video-processing"]`). SDK limitation: Use manual construction or helper. Stored only for registered accounts.
`pricing`	object	Pricing details: `model` (e.g., `pay_per_request`), `amount`, and `asset`

URL validation and registration

Kobaru validates all resource URLs before registering them in discovery:

Valid URLs: Only http:// and https:// schemes are accepted

RFC 1123 hostnames: Hostname format must follow standard rules

Production restrictions: Private IPs (192.168.x.x, 10.x.x.x) and localhost are blocked

If your URL fails validation, the discovery registration is silently skipped. Your payment verification is NOT affected.

This ensures the discovery catalog only contains publicly accessible APIs while allowing you to test locally during development.

What consumers see

When an AI agent or developer queries the discovery endpoint, your API appears with enriched metadata. Here is an example of a single resource in the response:

{
  "x402Version": 2,
  "items": [
    {
      "resource": "https://api.example.com/weather",
      "type": "http",
      "method": "GET",
      "x402Version": 2,
      "accepts": [
        {
          "scheme": "exact",
          "network": "eip155:8453",
          "maxAmountRequired": "1000",
          "asset": "USDC",
          "payTo": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "maxTimeoutSeconds": 60,
          "description": "Get current weather conditions for any location worldwide",
          "mimeType": "application/json",
          "outputSchema": {
            "input": {
              "method": "GET",
              "type": "http",
              "queryParams": {
                "location": { "type": "string" }
              }
            },
            "output": {
              "type": "application/json",
              "schema": {
                "properties": {
                  "temperature": { "type": "number" },
                  "conditions": { "type": "string" },
                  "humidity": { "type": "number" }
                }
              }
            }
          },
          "extra": {
            "asset": "USDC",
            "pricing": {
              "model": "pay_per_request",
              "amount": "1000",
              "asset": "USDC"
            }
          }
        }
      ],
      "lastUpdated": "2026-01-27T12:30:00.000Z",
      "provider": {
        "name": "WeatherCo",
        "description": "Leading weather data provider",
        "url": "https://weatherco.example.com"
      },
      "metadata": {
        "title": "Real-time Weather API",
        "description": "Get current weather conditions for any location worldwide",
        "tags": ["weather", "data", "real-time"]
      }
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

The enriched fields inside accepts -- description, mimeType, outputSchema, and extra -- are automatically extracted from your bazaar metadata. AI agents use these fields to understand your API's interface without reading external documentation.

Feature gating reference

As noted in the info field section, Kobaru gates certain fields to registered merchants. This table provides a quick reference for what each client type receives in the discovery catalog.

Registered account = merchant using an API key generated from the Kobaru Console. Unregistered account = testing with the public/anonymous client ID (no API key).

Field	Unregistered account	Registered account
Input/output schemas	✅ Stored	✅ Stored
Pricing information	✅ Stored	✅ Stored
Description	✅ Stored	✅ Stored
HTTP method	✅ Stored	✅ Stored
Tags	❌ Filtered	✅ Stored
Title	❌ Filtered	✅ Stored
Provider info	❌ Filtered	✅ Stored

Filtering is silent -- no errors are returned, and payment verification is never affected. Unregistered accounts can send these fields for local testing; they are simply not persisted to the catalog.

Getting started with discovery

Adding bazaar discovery to your API requires including the bazaar extension in your x402 payment middleware configuration. You have three approaches, depending on how much metadata you want to include.

Understanding enriched metadata

Important: The x402 v2 protocol supports tags, titles, and provider information. Any merchant can send this data by constructing the bazaar.info object manually. However:

Kobaru feature gating: Only registered merchants get enriched metadata (tags, title, provider) stored and served through discovery

Unregistered clients: Can send enrichment, but it gets silently filtered out at registration time (payment still succeeds)

SDK limitation: The standard declareDiscoveryExtension() function doesn't have parameters for enrichment (convenience wrapper only)

Approach 1: Basic discovery (SDK helper only)

Use the standard x402 SDK helper for basic discovery:

What you get:

✅ Listed in discovery endpoint

✅ Input/output schemas for AI agents

✅ Pricing information (from payment requirements)

❌ No tags (won't appear in tag-filtered searches)

❌ No custom title

❌ No provider information

Why the limitation? The SDK function doesn't expose parameters for tags, title, or provider - it's a convenience wrapper with limited functionality.

Approach 2: Manual construction (full protocol control)

Construct the bazaar extension manually to include enriched metadata:

What you get:

✅ Full-featured discovery with searchable tags (registered merchants only)

✅ Custom title for better branding (registered merchants only)

✅ Provider information for trust signals (registered merchants only)

✅ All benefits of basic discovery

Downside: Verbose syntax, easy to make mistakes in structure.

Approach 3: Enrichment helper (recommended)

Use our helper function for clean syntax with full enrichment:

Helper function location: discovery-helper.ts on GitHub - copy into your project.

What you get:

✅ Clean, type-safe API combining SDK + enrichment

✅ Full-featured discovery (registered merchants only)

✅ Less verbose than manual construction

✅ Single import, no additional dependencies

Note: Our helper is a convenience wrapper - it doesn't add protocol capabilities, it just makes manual enrichment cleaner.

Implementation examples

Helper function: discovery-helper.ts on GitHub

TypeScript (Hono/Express): Coinbase x402 bazaar example

Node.js: Kobaru API Paywall Cookbook

The bazaar extension is configured alongside your existing payment middleware. Once set up, discovery happens automatically on every payment verification -- there is nothing else to deploy, manage, or maintain.

Tip: If you are already using Kobaru's Standard SDK or Transparent Proxy, adding bazaar discovery is a configuration change, not a code rewrite.

Best practices

Register your account for full discovery features

Registered merchants get full discovery capabilities including tags, custom titles, and provider information. This significantly improves your API's discoverability:

Tag-based search: Your API appears in category-specific searches (?tags=ai,video-processing)

Brand visibility: Custom titles and provider information build trust

Professional presentation: Complete metadata makes your API stand out

Public clients get basic discovery (schemas and pricing only) for testing purposes.

Use meaningful tags (registered merchants only)

Tags enable filtering in the discovery catalog. Consumers can search for APIs using multiple tags simultaneously. Use lowercase, specific terms that accurately describe your API.

Good: ["finance", "exchange-rates", "real-time"]

Avoid: ["api", "data", "service"] (too generic)

Tip: Use 2-5 tags. Include your industry, capability type, and any distinguishing features. Without tags, your API won't appear in tag-filtered searches.

Write descriptive titles and descriptions

Your title and description are the first things consumers see. Make them specific and action-oriented.

Good: "Real-time currency exchange rates for 150+ fiat and crypto pairs"

Avoid: "My API" or "Data endpoint"

Title (registered merchants only): Use a concise, branded name (e.g., "YouTube Wisdom Extractor")

Description: Set this at the payment config level (description: "...") -- it's available for all merchants

Provide complete input and output schemas

AI agents rely on schemas to construct valid requests without trial and error. Include property types, descriptions, and any constraints that help an agent understand what to send and what to expect back.

This works for both public and registered merchants.

Include provider information (registered merchants only)

Provider details act as trust signals. Consumers are more likely to pay for an API when they can see the organization behind it. Include at minimum your name and url.

Keep descriptions concise

One or two sentences is ideal. Describe what the API does and what value it provides, not how it works internally.

Frequently asked questions

How do I opt in to discovery?

Include the extensions.bazaar object in your x402 payment configuration. That is the only requirement. There is no separate enrollment process.

How quickly will my API be listed?

Immediately. Your API appears in the discovery endpoint on the first payment verification that includes the bazaar extension.

Can I update my listing?

Yes. Your listing updates automatically every time a payment is verified. Change your bazaar extension metadata, and the next payment request will refresh the listing.

Who can see my listing?

Anyone. The discovery endpoint is public and requires no authentication. This is by design -- the goal is maximum visibility for your API.

Is there a cost for discovery?

No. Bazaar discovery is included with Kobaru Gateway at no additional charge.

Why are tags and provider info only for registered merchants?

The x402 v2 protocol supports enriched metadata for everyone - any merchant can send tags, titles, and provider information in the bazaar extension. However, Kobaru's implementation adds feature gating:

You can send enriched metadata: The protocol allows it, and you can include it in your payment requests

Storage is feature-gated: Only registered merchants get enriched metadata stored in the discovery catalog

Public clients get filtered: If you send enrichment as a unregistered account, it's silently discarded at registration time

Why this approach?

Prevents spam/abuse: Anonymous unregistered accounts can't flood the catalog with misleading tags

Encourages registration: Premium discovery features incentivize account creation (it's free!)

Maintains quality: Verified merchants with contact information provide higher-quality listings

Fail-safe: Public clients can still test with enrichment locally without breaking payments

See the feature gating reference table for the full field-by-field breakdown. In short: unregistered accounts get schemas, pricing, and descriptions; registered merchants additionally get tags, titles, and provider information.

If you are using the unregistered account for testing and want full discovery features, register for a Kobaru account (it's free).

What happens if I send tags as a unregistered account?

At protocol level: Nothing breaks - you can send the data without errors.

At Kobaru storage level: The enriched fields (tags, title, provider) are silently filtered during registration. Your API still appears in discovery with basic metadata (schemas, pricing, description), and payment verification works normally.

You won't receive any error messages - the enriched fields are simply not stored in the database. This allows you to:

Test enrichment locally during development

Use the same code for public and registered accounts

Upgrade to registered account without code changes

What if discovery registration fails?

It does not affect your payments. Discovery registration is a background process. If it fails (for example, due to invalid metadata or URL validation), the payment verification completes normally. Common reasons for registration failure:

Invalid URL format - URL must use http:// or https://

Private/localhost URL in production - Only public URLs are allowed in production (localhost works in staging/dev)

Invalid hostname - Hostname must follow RFC 1123 rules

Oversized metadata - Info must be under 8KB

Fix the issue, and the next payment request will register successfully.

Can I use enriched metadata without the helper function?

Yes, absolutely! The x402 v2 protocol natively supports tags, titles, and provider information. You have three options:

SDK helper only (basic): Use declareDiscoveryExtension() - doesn't expose enrichment parameters

Manual construction (full protocol): Build the bazaar.info object yourself with all fields

Our helper (convenience): Use enrichDiscoveryExtension() - combines SDK convenience with enrichment

Our helper function is purely a developer experience improvement - it doesn't add any protocol capabilities. If you prefer manual construction or already have working code, keep using it! The feature gating (registered vs public) applies regardless of which approach you use.

Why doesn't declareDiscoveryExtension() support tags/title/provider?

The standard x402 SDK's declareDiscoveryExtension() is a convenience wrapper designed for common use cases. It focuses on the most essential fields (method, input schema, output schema) and doesn't expose parameters for enrichment.

This is an SDK limitation, not a protocol limitation. The x402 v2 specification fully supports tags, titles, and provider information - you just need to construct the bazaar.info object manually (see Approach 2) or use our helper (see Approach 3).

We built the enrichDiscoveryExtension() helper to bridge this gap with a clean API.

Can I remove my API from the catalog?

You can disable discovery on Kobaru Console. Alternatively, remove the extensions.bazaar object from your payment configuration, and your listing will not receive further updates.

Does discovery work with all integration methods?

Yes. Any integration that sends the bazaar extension in the x402 payment payload will trigger discovery registration. This applies to the Standard SDK, Transparent Proxy (when configured with bazaar metadata), and Direct API integrations.

Security and reliability

Kobaru's bazaar discovery is production-hardened with enterprise-grade reliability and security:

Guaranteed registration

Your API is guaranteed to appear in the discovery catalog after a successful payment, even under high load.

DoS protection and validation

Discovery metadata is protected against malicious inputs:

Info metadata limited to 8KB (prevents memory exhaustion)

URL validation (blocks localhost, private IPs, invalid schemes in production)

Hostname validation (RFC 1123 compliance, max 253 characters)

Schema validation (optional custom schemas up to 4KB)

Invalid resources are silently rejected without affecting payment processing. These limits are generous for legitimate use cases but prevent abuse.

Privacy controls

Only documented fields from your bazaar extension are publicly served. Internal fields accidentally included via .passthrough() are automatically filtered out, preventing information disclosure.

High performance

Discovery queries are cached for 60 seconds and use optimized database indexes. The catalog can handle thousands of requests per second with sub-10ms response times.

Zero payment impact

Discovery registration runs asynchronously and never affects payment verification. Even if registration fails, your payment succeeds normally.

Next steps

Pricing your API -- Set prices that maximize revenue

Standard SDK guide -- Full control with TypeScript middleware

Available blockchains -- Supported networks and assets

What is Kobaru? -- Platform overview and integration options

Bazaar discovery

Bazaar discovery#

Why discovery matters#

How it works#

Key benefits#

Zero-effort listing#

Global visibility#

Rich metadata for AI agents#

Automatic updates#

Provider trust signals#

Industry-standard protocol#

What makes Kobaru's discovery different#

Discovery endpoint#

Query parameters#

Example request#

Rate limiting#

Bazaar extension fields#

The info field#

Info field reference#

URL validation and registration#

What consumers see#

Feature gating reference#

Getting started with discovery#

Understanding enriched metadata#

Approach 1: Basic discovery (SDK helper only)#

Approach 2: Manual construction (full protocol control)#

Approach 3: Enrichment helper (recommended)#

Implementation examples#

Best practices#

Register your account for full discovery features#

Use meaningful tags (registered merchants only)#

Write descriptive titles and descriptions#

Provide complete input and output schemas#

Include provider information (registered merchants only)#

Keep descriptions concise#

Frequently asked questions#

How do I opt in to discovery?#

How quickly will my API be listed?#

Can I update my listing?#

Who can see my listing?#

Is there a cost for discovery?#

Why are tags and provider info only for registered merchants?#

What happens if I send tags as a unregistered account?#

What if discovery registration fails?#

Can I use enriched metadata without the helper function?#

Why doesn't declareDiscoveryExtension() support tags/title/provider?#

Can I remove my API from the catalog?#

Does discovery work with all integration methods?#

Security and reliability#

Guaranteed registration#

DoS protection and validation#

Privacy controls#

High performance#

Zero payment impact#

Next steps#

Bazaar discovery

Why discovery matters

How it works

Key benefits

Zero-effort listing

Global visibility

Rich metadata for AI agents

Automatic updates

Provider trust signals

Industry-standard protocol

What makes Kobaru's discovery different

Discovery endpoint

Query parameters

Example request

Rate limiting

Bazaar extension fields

The `info` field

Info field reference

URL validation and registration

What consumers see

Feature gating reference

Getting started with discovery

Understanding enriched metadata

Approach 1: Basic discovery (SDK helper only)

Approach 2: Manual construction (full protocol control)

Approach 3: Enrichment helper (recommended)

Implementation examples

Best practices

Register your account for full discovery features

Use meaningful tags (registered merchants only)

Write descriptive titles and descriptions

Provide complete input and output schemas

Include provider information (registered merchants only)

Keep descriptions concise

Frequently asked questions

How do I opt in to discovery?

How quickly will my API be listed?

Can I update my listing?

Who can see my listing?

Is there a cost for discovery?

Why are tags and provider info only for registered merchants?

What happens if I send tags as a unregistered account?

What if discovery registration fails?

Can I use enriched metadata without the helper function?

Why doesn't declareDiscoveryExtension() support tags/title/provider?

Can I remove my API from the catalog?

Does discovery work with all integration methods?

Security and reliability

Guaranteed registration

DoS protection and validation

Privacy controls

High performance

Zero payment impact

Next steps