API Evangelist enhancements for KyberSwap Aggregator API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for KyberSwap Aggregator API
  version: 1.0.0
extends: openapi/kyber-network-aggregator-openapi.yml
x-generated: '2026-07-19'
x-method: generated
x-source: API Evangelist enrichment pipeline; facts harvested from KyberSwap documentation
actions:
- target: $.info
  description: Record provider contact, docs and licence-free public access.
  update:
    contact:
      name: KyberSwap Business Development
      email: business@kyber.network
      url: https://discord.gg/kyberswap
    x-docs: https://docs.kyberswap.com/developer-guide/aggregator-api/aggregator-api-specification/evm-swaps
    x-api-catalog: https://kyberswap.com/.well-known/api-catalog
    x-status-page: https://kyber.statuspage.io
- target: $.info
  description: Document the unauthenticated access model and client identification header.
  update:
    x-authentication:
      required: false
      note: No API keys, tokens or secrets. Identify your client with the x-client-id header.
      artifact: authentication/kyber-network-authentication.yml
- target: $.info
  description: Attach the published rate limit and its tiering mechanism.
  update:
    x-rate-limit:
      default: 3 rps
      tiered_by: x-client-id
      exceeded: HTTP 429
      upgrade_contact: business@kyber.network
      artifact: rate-limits/kyber-network-rate-limits.yml
- target: $.info
  description: Attach the error catalog; errors are a proprietary {code,message} envelope, not RFC 9457.
  update:
    x-error-catalog:
      format: proprietary
      envelope: '{ "code": <int>, "message": "<string>" }'
      artifact: errors/kyber-network-error-codes.yml
- target: $.info
  description: Flag the absence of an idempotency mechanism so agents do not assume safe retries.
  update:
    x-idempotency:
      supported: false
      note: No idempotency key. Build/quote operations are read-only and safe to retry; submissions are
        not. Replay protection is the wallet nonce on-chain.
      artifact: conventions/kyber-network-conventions.yml
- target: $.servers
  description: Confirm the production host advertised in the RFC 9727 API catalog.
  update:
  - url: https://aggregator-api.kyberswap.com
    description: Production, advertised via https://kyberswap.com/.well-known/api-catalog
- target: $.paths.*.*
  description: Mark every operation as requiring the client identification header for full rate-limit
    tiering.
  update:
    x-client-id-header: x-client-id
- target: $.paths['/{chain}/route/encode'].get
  description: Mark the pre-v1 encode endpoint as the documented Legacy API superseded by the v1 two-step
    flow.
  update:
    deprecated: true
    x-superseded-by:
    - get-route
    - post-route-encoded
    x-migration-guide: https://docs.kyberswap.com/developer-guide/aggregator-api/how-to-guides/execute-a-swap-with-the-aggregator-api/upgrading-to-apiv1
    x-sunset-date: null
- target: $.paths['/{chain}/api/v1/routes'].get
  description: Record the provider quote-freshness guidance.
  update:
    x-cache-ttl-seconds: 10
    x-cache-note: Do not cache routes client-side for more than 5-10 seconds; quotes reflect live on-chain
      liquidity.