Auxen Pay with USDC API

openapi: 3.2.0
info:
  title: Auxen Headless Pay with USDC API
  version: 1.3.0
  description: 'Programmatic API for Auxen: hire and manage AI workers (`/v1/workers`,

    `/v1/connections`, approvals; also over MCP and A2A), and deploy and

    manage private open-weight model endpoints. Anything a human can do in

    the dashboard, an agent can do via this API.


    **Two key types:**

    - `auxen_live_…` / `auxen_test_…` — your account-level **agent management**

    key. Authorizes deploying, switching models, and billing operations.

    - `auxk_…` — a per-deployment **inference** key returned in the `api_key`

    field of every deployment object. Authorizes inference calls on that

    deployment only. Hand it to downstream services without giving up

    management rights.


    **Billing:**

    All Auxen deployments are billed **pay-as-you-go** from a prepaid USD credit

    balance, per minute of active time; billing stops when a deployment is

    paused or deleted. Throughput levels (Standard, Double, Quad, Max)

    increase simultaneous request handling at the same model quality. Top up

    the balance with `POST /v1/billing/add-credits`.


    **2026 renames:** `/v1/provision` → `/v1/deploy`, `/v1/instances` →

    `/v1/deployments`, `/scale` → `/throughput`, `/wake` → `/resume`.

    Old routes keep working until 2027-04-02 and send `Deprecation`,

    `Sunset`, and `Link` headers. Responses carry new and old field names

    side by side (`deployment_id` + `instance_id`, `throughput` +

    `capacity`, `rate_per_hour` + `hourly_rate`, `ready_estimate` +

    `estimated_ready_at`). Migration guide: https://auxen.ai/docs/api/migration'
  contact:
    email: hello@auxen.ai
    url: https://auxen.ai/contact
servers:
- url: https://api.auxen.ai
  description: Production
tags:
- name: Pay with USDC
paths:
  /x402/v1:
    get:
      summary: 'Pay with USDC (x402): network, pay-to address, limits'
      tags:
      - Pay with USDC
      security: []
      responses:
        '200':
          description: '`enabled`, `network` (CAIP-2), `asset`, `pay_to`, `limits` {min_usd, max_usd, per_wallet_per_day_usd}, `endpoints`.'
      operationId: getX402V1
      x-operation-id-source: derived
  /x402/v1/workers:
    post:
      summary: Hire a worker and pay its budget in USDC (x402), no account needed
      tags:
      - Pay with USDC
      security:
      - {}
      - AgentKey: []
      description: Same body as POST /v1/workers. The request is fully checked first. Without a payment the reply is 402 with a `PAYMENT-REQUIRED` header (x402 v2, scheme `exact`, USDC; price = budget_usd). Repeat with `PAYMENT-SIGNATURE`. The wallet's first payment creates an account and returns `account.api_key` once. An optional live key links the wallet to that account instead. Unspent budget returns to the balance when the worker is fired.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: As POST /v1/workers.
      responses:
        '202':
          description: '`worker`, `account` {wallet, balance_usd, api_key?}, `payment` {payment_id, amount_usd, network, transaction}. `PAYMENT-RESPONSE` header.'
        '402':
          description: Payment required (or the payment didn't match or couldn't settle; nothing was charged).
        '403':
          description: X402_WALLET_MISMATCH or X402_WALLET_REFUSED
        '409':
          description: X402_PAYMENT_REPLAYED
        '429':
          description: X402_DAILY_LIMIT
      operationId: postX402V1Workers
      x-operation-id-source: derived
  /x402/v1/workers/{workerId}/budget:
    post:
      summary: Top up a worker's budget in USDC (x402)
      tags:
      - Pay with USDC
      security:
      - {}
      - AgentKey: []
      parameters:
      - name: workerId
        in: path
        required: true
        schema:
          type: string
      description: Only the wallet that owns the worker, or its account's key, can top it up; checked before any price is quoted. Price = add_usd.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - add_usd
              properties:
                add_usd:
                  type: number
                  minimum: 1
                  maximum: 500
      responses:
        '200':
          description: '`worker`, `account`, `payment`.'
        '402':
          description: Payment required.
        '403':
          description: X402_WALLET_MISMATCH
      operationId: postX402V1WorkersByWorkerIdBudget
      x-operation-id-source: derived
  /x402/v1/credits:
    post:
      summary: Add prepaid credit in USDC (x402)
      tags:
      - Pay with USDC
      security:
      - {}
      - AgentKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - amount_usd
              properties:
                amount_usd:
                  type: number
                  minimum: 1
                  maximum: 500
      responses:
        '200':
          description: '`account`, `payment`.'
        '402':
          description: Payment required.
      operationId: postX402V1Credits
      x-operation-id-source: derived
  /x402/v1/refunds:
    get:
      summary: Refundable USDC credit and past refunds
      tags:
      - Pay with USDC
      security:
      - AgentKey: []
      responses:
        '200':
          description: '`refundable_usd`, `wallet`, `balance_usd`, `refunds`.'
      operationId: getX402V1Refunds
      x-operation-id-source: derived
    post:
      summary: Refund unspent USDC credit to the paying wallet
      tags:
      - Pay with USDC
      security:
      - AgentKey: []
      description: 'Refunds go only to the wallet that paid, never more than it paid in USDC (card credit is never paid out in crypto). The amount is held off the balance and reviewed by the Auxen team, usually within one business day: `awaiting_approval` → `sent` (with `transaction`) or `rejected` (back on the balance). Omit amount_usd to refund everything refundable.'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                amount_usd:
                  type: number
                  minimum: 0.1
      responses:
        '202':
          description: The refund, `awaiting_approval`.
        '400':
          description: X402_REFUND_AMOUNT (with refundable_usd) or X402_NO_WALLET
        '403':
          description: X402_WALLET_REFUSED
      operationId: postX402V1Refunds
      x-operation-id-source: derived
  /x402/v1/refunds/{refundId}:
    get:
      summary: One refund's status
      tags:
      - Pay with USDC
      security:
      - AgentKey: []
      parameters:
      - name: refundId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The refund.
        '404':
          description: X402_REFUND_NOT_FOUND
      operationId: getX402V1RefundsByRefundId
      x-operation-id-source: derived
components:
  securitySchemes:
    AgentKey:
      type: http
      scheme: bearer
      bearerFormat: auxen_live_xxx | auxen_test_xxx
      description: Account-level key. Generate at /dashboard/api-keys.
    DeploymentKey:
      type: http
      scheme: bearer
      bearerFormat: auxk_xxx
      description: Per-deployment key from the `api_key` field of a deployment object.