@@ -11339,6 +11339,31 @@ components:
         - 'failure_reason'
         - 'created_at'
       type: 'object'
+    CreditPurchasePaymentRequired:
+      properties:
+        challengeId:
+          type: 'string'
+        detail:
+          type: 'string'
+        setup:
+          description: 'The agent setup guide, `GET /api/v1/credits/purchases/setup`.'
+          example: 'https://openrouter.ai/api/v1/credits/purchases/setup'
+          type: 'string'
+        status:
+          enum:
+            - 402
+          type: 'number'
+        title:
+          type: 'string'
+        type:
+          example: 'https://paymentauth.org/problems/payment-required'
+          type: 'string'
+      required:
+        - 'type'
+        - 'title'
+        - 'status'
+        - 'setup'
+      type: 'object'
     CreditPurchaseResponse:
       properties:
         data:
@@ -42743,10 +42768,24 @@ paths:
           description: 'Unauthorized - Authentication required or invalid credentials'
         '402':
           content:
-            application/json:
+            application/problem+json:
               schema:
-                $ref: '#/components/schemas/CreditPurchaseResponse'
-          description: 'Payment required. An unpaid request carries the MPP challenge in `WWW-Authenticate`.'
+                $ref: '#/components/schemas/CreditPurchasePaymentRequired'
+          description: 'Payment required. An unpaid request carries the MPP challenge in `WWW-Authenticate`, and a `Link: rel="help"` header plus a `setup` field pointing at the agent setup guide, `GET /api/v1/credits/purchases/setup`.'
+          headers:
+            Link:
+              description: 'The agent setup guide.'
+              required: true
+              schema:
+                description: 'The agent setup guide.'
+                example: '<https://openrouter.ai/api/v1/credits/purchases/setup>; rel="help"'
+                type: 'string'
+            WWW-Authenticate:
+              description: 'The MPP challenge: `Payment id="...", method="tempo", intent="charge", ...`.'
+              required: true
+              schema:
+                description: 'The MPP challenge: `Payment id="...", method="tempo", intent="charge", ...`.'
+                type: 'string'
         '403':
           content:
             application/json:
@@ -42911,6 +42950,40 @@ paths:
       x-fern-ignore: true
       x-hidden: true
       x-speakeasy-ignore: true
+  /credits/purchases/setup:
+    get:
+      operationId: 'listCreditsPurchasesSetup'
+      responses:
+        '200':
+          content:
+            text/markdown:
+              schema:
+                type: 'string'
+          description: 'Markdown document, readable without a key.'
+      security: []
+      summary: 'Agent setup guide for buying credits with a machine payment'
+      tags:
+        - 'Credits'
+      x-fern-ignore: true
+      x-hidden: true
+      x-speakeasy-ignore: true
+  /credits/purchases/SKILL.md:
+    get:
+      operationId: 'listCreditsPurchasesSKILL.md'
+      responses:
+        '200':
+          content:
+            text/markdown:
+              schema:
+                type: 'string'
+          description: 'Markdown document, readable without a key.'
+      security: []
+      summary: 'Agent skill for buying OpenRouter credits'
+      tags:
+        - 'Credits'
+      x-fern-ignore: true
+      x-hidden: true
+      x-speakeasy-ignore: true
   /datasets/app-rankings:
     get:
       description: "Returns the top public apps on OpenRouter ranked by token usage inside the requested\ndate window, matching the public apps marketplace on openrouter.ai/apps. Token totals\nare `prompt_tokens + completion_tokens`; hidden and private apps are excluded and\ntraffic from related app aliases is merged into the canonical visible app.\n\n`sort=popular` (default) ranks by total token volume inside the window.\n`sort=trending` ranks by absolute excess token growth: window volume minus the average\nvolume of the three equal-length periods immediately preceding the window. Apps with\nno excess growth are omitted, so `trending` may return fewer than `limit` rows.\n\nFilter with `category` (marketplace category group, e.g. `coding`) or `subcategory`\n(e.g. `cli-agent`). Ranks are re-numbered 1..N after filtering. Page with `offset` —\n`rank` stays absolute, so the first row of `offset=50` is `rank: 51`.\n\nAuthenticate with any valid OpenRouter API key (same key used for inference).\nRate-limited to 30 requests/minute per key and 500 requests/day per account.\n\nWhen republishing or quoting this dataset, OpenRouter must be cited as:\n\"Source: OpenRouter (openrouter.ai/apps), as of {as_of}.\"\n\nToken counts come from each upstream provider's own tokenizer, so a token attributed\nto one app is not directly comparable to a token attributed to another app whose\ntraffic flows through a different provider.\n\nLicensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): reuse and republish with attribution to OpenRouter."