Provider onboarding

Naven uses OpenAPI as the canonical provider contract. A provider submits one HTTPS URL, normally:

https://provider.example/openapi.json

The document must use OpenAPI 3.0 or 3.1 and include an HTTPS servers URL. Every Marketplace operation should have a stable operationId, summary, description, complete inputs, success response, and examples or defaults where they help a caller construct a valid request.

Free operations

A free operation declares:

{
  "operationId": "getPositions",
  "x-naven-access": {
    "mode": "free",
    "verification": "live-2xx"
  },
  "responses": {
    "200": {
      "description": "Successful response"
    }
  }
}

It must not include x-payment-info. Naven sends a safe example request and publishes the operation only after the live endpoint returns a successful response without a payment header.

An operation without x-naven-access is not assumed to be free. Naven may use a provider-owned discovery endpoint as supplemental evidence, but ambiguous operations remain candidates until reviewed or verified.

Paid operations

A paid operation declares a 402 response and the Payment Discovery x-payment-info extension:

{
  "operationId": "simplePrice",
  "x-naven-access": {
    "mode": "paid",
    "verification": "live-402"
  },
  "x-payment-info": {
    "offers": [
      {
        "intent": "charge",
        "method": "x402",
        "amount": "10000",
        "currency": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
        "description": "0.01 USDG per successful request"
      }
    ]
  },
  "x-x402-info": {
    "x402Version": 2,
    "scheme": "exact",
    "network": "eip155:4663",
    "asset": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
    "assetDecimals": 6,
    "currency": "USDG"
  },
  "responses": {
    "200": {
      "description": "Successful response"
    },
    "402": {
      "description": "Payment Required"
    }
  }
}

The discovered amount is expressed in the asset's smallest unit. For six-decimal USDG, 10000 is 0.01 USDG.

OpenAPI payment data is advisory. Naven sends a safe request without a payment signature and treats the live 402 Payment Required challenge as authoritative. The operation is published as paid only when the challenge confirms:

• x402 version 2
• the exact payment scheme
• Robinhood Chain (eip155:4663)
• the supported USDG contract

Import behavior

Naven stores the OpenAPI document and any provider-owned discovery response as observations. The OpenAPI operation supplies the HTTP method, URL, input schema, response schema, name, and description. Live verification supplies the final access mode and, for a paid operation, the authoritative amount and recipient.

Free and paid operations can belong to the same provider. Naven publishes them in one provider page while keeping their execution flows distinct: free operations run directly, and paid operations complete the x402 exchange first.

Naven's public /discovery/resources endpoint is generated from the verified Registry. Providers do not need to implement that endpoint themselves.