From a39dc09fe19a9ed3efa05e2fc8c75f637854566c Mon Sep 17 00:00:00 2001 From: dgenAI Date: Thu, 16 Apr 2026 18:09:18 +0200 Subject: [PATCH 1/3] feat(management): accept OpenAPI parameters, requestBody, or full spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extend CreateApiInput and ApiEndpointInput so callers can describe each endpoint's query/path/header parameters and request body schema — or pass a full OpenAPI 3.x spec via the new `openApi` field. Without this, APIs created through the Management API appear in the marketplace with no testable inputs because the UI has no schema to render. --- src/management.ts | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/src/management.ts b/src/management.ts index b33e5b5..3556bc7 100644 --- a/src/management.ts +++ b/src/management.ts @@ -36,11 +36,36 @@ export interface RelaiApi { updatedAt: string; } +/** + * OpenAPI-style parameter descriptor (query / path / header). + * Shown on the marketplace test form so buyers can fill required inputs. + */ +export interface OpenApiParameter { + name: string; + in: 'query' | 'path' | 'header'; + required?: boolean; + description?: string; + schema?: Record; +} + +/** + * OpenAPI-style request body descriptor. + * Accepts either the full OpenAPI shape + * ({ required, content: { 'application/json': { schema } } }) + * or a simplified { description?, required?: string[], properties?: {...} } shape. + */ +export type OpenApiRequestBody = Record; + export interface ApiEndpointInput { path: string; method: string; usdPrice: number; enabled?: boolean; + description?: string; + /** Query / path / header parameter descriptors (OpenAPI shape). */ + parameters?: OpenApiParameter[]; + /** Request body descriptor for POST/PUT/PATCH endpoints (OpenAPI shape). */ + requestBody?: OpenApiRequestBody; } export interface ApiEndpoint extends ApiEndpointInput { @@ -61,6 +86,12 @@ export interface CreateApiInput { websiteUrl?: string; logoUrl?: string; endpoints?: ApiEndpointInput[]; + /** + * Full OpenAPI 3.x specification (object or JSON string). When provided, the spec + * is saved and the marketplace UI renders full schemas. If `endpoints` is omitted, + * endpoints are derived from the spec's paths with a default price. + */ + openApi?: Record | string; } export interface UpdateApiInput { From ba85de1d53b55e044ca2311ab2364c594ba859f2 Mon Sep 17 00:00:00 2001 From: dgenAI Date: Thu, 16 Apr 2026 20:39:21 +0200 Subject: [PATCH 2/3] feat(management): accept facilitator and x402Version on createApi Expose optional facilitator and x402Version fields on CreateApiInput (already accepted server-side) so TypeScript callers can pick the settlement facilitator per API. Defaults to the first supported facilitator on the network and the newest x402 version the pair supports. Server rejects unsupported (facilitator, network, version) triples. --- src/management.ts | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/src/management.ts b/src/management.ts index 3556bc7..3bd5843 100644 --- a/src/management.ts +++ b/src/management.ts @@ -56,6 +56,36 @@ export interface OpenApiParameter { */ export type OpenApiRequestBody = Record; +/** + * Known facilitator identifiers. `string` is kept in the union so new + * facilitators can be passed without bumping the SDK — the server validates. + * + * Support matrix (at time of writing — server is source of truth): + * - `payai` solana, solana-devnet, base, base-sepolia, peaq, polygon, sei (v1/v2; peaq+polygon+sei = v1) + * - `dexter` solana, base (v2) + * - `openfacilitator` solana, base (v2) + * - `relai` solana, solana-devnet, base, base-sepolia, skale-base, skale-base-sepolia, avalanche, polygon, ethereum, telos (v2) + * - `autoincentive` base, base-sepolia (v2) + * - `stratum` solana, base (v2) + * - `thirdweb` ethereum (v1) + * - `0xgasless` avalanche (v2) + * - `custom` most networks (v1/v2) + */ +export type Facilitator = + | 'payai' + | 'dexter' + | 'openfacilitator' + | 'relai' + | 'autoincentive' + | 'stratum' + | 'thirdweb' + | '0xgasless' + | 'custom' + | (string & {}); + +/** x402 protocol version. */ +export type X402Version = 1 | 2; + export interface ApiEndpointInput { path: string; method: string; @@ -82,6 +112,18 @@ export interface CreateApiInput { /** EVM wallet for cross-chain payments. Only relevant when network is Solana. */ evmCrossChainWallet?: string; network: string; + /** + * Facilitator to settle payments through. Defaults to the first supported + * facilitator on `network` (e.g. `payai` on solana/base, `relai` on skale-base, + * avalanche, telos, ...). Server rejects unsupported (facilitator, network) + * combinations with a 400. + */ + facilitator?: Facilitator; + /** + * x402 protocol version. Defaults to the newest version the (facilitator, network) + * pair supports. Validated server-side. + */ + x402Version?: X402Version; description?: string; websiteUrl?: string; logoUrl?: string; From 1fce22b91902c5b919d8d2aea3db337971d5b4d4 Mon Sep 17 00:00:00 2001 From: dgenAI Date: Thu, 16 Apr 2026 20:45:25 +0200 Subject: [PATCH 3/3] docs(management): clarify default facilitator and version MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reflect the server-side default resolution: createApi without an explicit facilitator uses relai whenever the network supports it (every network except peaq and sei) and x402Version defaults to 2 wherever the pair supports v2. No code change — JSDoc only. --- src/management.ts | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/src/management.ts b/src/management.ts index 3bd5843..6e06859 100644 --- a/src/management.ts +++ b/src/management.ts @@ -113,15 +113,16 @@ export interface CreateApiInput { evmCrossChainWallet?: string; network: string; /** - * Facilitator to settle payments through. Defaults to the first supported - * facilitator on `network` (e.g. `payai` on solana/base, `relai` on skale-base, - * avalanche, telos, ...). Server rejects unsupported (facilitator, network) - * combinations with a 400. + * Facilitator to settle payments through. Defaults to `relai` whenever the + * network supports it (every network except `peaq` and `sei`, which fall back + * to `payai`). Server rejects unsupported (facilitator, network) combinations + * with a 400. */ facilitator?: Facilitator; /** - * x402 protocol version. Defaults to the newest version the (facilitator, network) - * pair supports. Validated server-side. + * x402 protocol version. Defaults to `2` whenever the (facilitator, network) + * pair supports v2; v1-only pairs (e.g. `thirdweb` on ethereum) fall back + * to v1. Validated server-side. */ x402Version?: X402Version; description?: string;