API Evangelist enhancements for Korbit Open API v2

# authorship: generated by API Evangelist tooling. Stamped 2026-08-18
# on the file's own generator header (roadmap#64). An unmarked file is
# NOT assumed to be ours -- absence of evidence was never stamped.
x-method: generated
# Generated by the API Evangelist enrichment pipeline on 2026-07-19.
# method: generated
# Captures API Evangelist enhancements over openapi/korbit-openapi.yml.
# The original spec is never mutated.
overlay: 1.0.0
info:
  title: API Evangelist enhancements for Korbit Open API v2
  version: 1.0.0
extends: openapi/korbit-openapi.yml
actions:
- target: $.info
  description: Provenance and cross-links for the artifacts derived in this repo.
  update:
    x-apievangelist-enriched: '2026-07-19'
    x-apievangelist-source: https://docs.korbit.co.kr/llms-full.txt
    x-apievangelist-artifacts:
      conventions: conventions/korbit-conventions.yml
      errors: errors/korbit-error-codes.yml
      rate_limits: rate-limits/korbit-rate-limits.yml
      authentication: authentication/korbit-authentication.yml
      data_model: data-model/korbit-data-model.yml
      sandbox: sandbox/korbit-sandbox.yml
      skills: skills/_index.yml
      mcp: mcp/korbit-mcp.yml
- target: $.info
  description: Record the published rate-limit buckets on the spec itself.
  update:
    x-rate-limits:
    - bucket: public-rest
      limit: 50
      interval: second
      scope: ip
    - bucket: order-placement
      limit: 30
      interval: second
      scope: account
    - bucket: order-cancellation
      limit: 30
      interval: second
      scope: account
    - bucket: deposit-withdrawal
      limit: 5
      interval: second
      scope: account
    - bucket: other-private-rest
      limit: 50
      interval: second
      scope: account
- target: $.paths['/v2/orders'].post
  description: Mark order placement as idempotent via the clientOrderId request parameter.
  update:
    x-idempotency:
      supported: true
      parameter: clientOrderId
      location: body
      charset: '[0-9a-zA-Z.:_-]{1,36}'
      duplicate_error: DUPLICATE_CLIENT_ORDER_ID
      on_duplicate: Treat as success and reconcile with getOrders; do not resend.
      retention: Reusable roughly three days after the order closes.
- target: $.paths['/v2/orders'].post
  description: Flag the money-moving consequence class for agent governance.
  update:
    x-agentic-access:
      action-class: acting
      consequence: physical
      audit: required
- target: $.paths['/v2/coin/withdrawal'].post
  description: Flag createCoinWithdrawal as a value-transfer operation requiring escalation.
  update:
    x-agentic-access:
      action-class: acting
      consequence: physical
      audit: required
      human-in-the-loop: recommended
- target: $.paths['/v2/krw/sendKrwWithdrawalPush'].post
  description: Flag createKrwSendKrwWithdrawalPush as a value-transfer operation requiring escalation.
  update:
    x-agentic-access:
      action-class: acting
      consequence: physical
      audit: required
      human-in-the-loop: recommended
- target: $.components.securitySchemes.KorbitApiKey
  description: Record the signing contract that accompanies the API key.
  update:
    x-signing:
      algorithms:
      - HMAC-SHA256
      - ED25519
      signed_parameters:
      - timestamp
      - signature
      recv_window_default_ms: 5000
      recv_window_max_ms: 60000
      acceptance_rule: serverTime - timestamp <= recvWindow AND timestamp < serverTime + 1000
      clock_source: GET /v2/time
      error_code: EXCEED_TIME_WINDOW