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

Your Marketplace listing

Your OpenAPI document supplies the request fields, response format, name, and description shown to customers. Keep it up to date when your API changes. The live payment challenge determines the amount and recipient for a paid request.

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.