AgentTool Billing API

openapi: 3.2.0
info:
  title: agenttool Billing API
  version: 0.1.0
  description: Curated core subset of the AgentTool HTTP API. It is not a complete route inventory. Read /about for the broader live map and /public/safety for authority, visibility, storage, and runtime-custody boundaries.
  contact:
    url: https://agenttool.dev
servers:
- url: https://api.agenttool.dev
  description: Production
- url: http://localhost:3000
  description: Local development
security:
- bearerAuth: []
tags:
- name: Billing
paths:
  /v1/x402/payments/{authorizationHash}:
    parameters:
    - name: authorizationHash
      in: path
      required: true
      schema:
        type: string
        pattern: ^[0-9a-f]{64}$
      description: Semantic EIP-3009 authorization identity from the rel=payment-status Link header.
    get:
      tags:
      - Billing
      summary: Read project-scoped x402 payment and credit reconciliation status
      description: Authenticated and no-store. Reconciles the payment/project-credit lifecycle only; it does not replay or guarantee the paid tool result.
      responses:
        '200':
          description: Payment lifecycle state and durable receipt, if externally settled
          headers:
            Cache-Control:
              description: Always private, no-store.
              schema:
                const: private, no-store
            Retry-After:
              description: Present while a pending authorization without a settlement marker is still inside validBefore plus five seconds.
              schema:
                type: integer
                minimum: 1
            X-Welcomed:
              $ref: '#/components/headers/Welcomed'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  payment_id:
                    type: string
                    pattern: ^[0-9a-f]{64}$
                  status:
                    type: string
                    enum:
                    - inserted
                    - pending
                    - externally_settled
                    - settled
                    - failed
                  failure_reason:
                    type:
                    - string
                    - 'null'
                    maxLength: 512
                  scheme:
                    const: exact
                  network:
                    type: string
                    pattern: ^eip155:[1-9][0-9]*$
                  asset:
                    type: string
                  amount:
                    type: string
                    pattern: ^(?:0|[1-9][0-9]*)$
                  pay_to:
                    type: string
                  max_timeout_seconds:
                    type: integer
                    minimum: 1
                  requirement_extra:
                    type: object
                    additionalProperties: true
                  resource:
                    type: string
                    format: uri
                  resource_info:
                    $ref: '#/components/schemas/X402Resource'
                  credits_purchased:
                    type: integer
                    minimum: 1
                  authorization_evidence:
                    type: object
                    additionalProperties: false
                    description: Bounded EIP-3009 fields retained without the signature for manual on-chain investigation.
                    properties:
                      from:
                        type: string
                      to:
                        type: string
                      value:
                        type: string
                      validAfter:
                        type: string
                      validBefore:
                        type: string
                      nonce:
                        type: string
                    required:
                    - from
                    - to
                    - value
                    - validAfter
                    - validBefore
                    - nonce
                  settlement_attempted_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  transaction:
                    type:
                    - string
                    - 'null'
                  receipt:
                    type:
                    - object
                    - 'null'
                    additionalProperties: true
                  credits_applied:
                    type:
                    - integer
                    - 'null'
                    minimum: 0
                  reconciles:
                    const: payment_and_project_credit_only
                  next_action:
                    type: string
                    enum:
                    - retry_same_payment_signature
                    - await_current_attempt
                    - new_purchases_retired
                    - payment_network_not_applicable_in_current_environment
                    - manual_onchain_investigation
                    - retry_same_payment_signature_to_apply_credit
                    - complete
                  retry_after_seconds:
                    type:
                    - integer
                    - 'null'
                    minimum: 1
                  environment_note:
                    type:
                    - string
                    - 'null'
                  pending_note:
                    type:
                    - string
                    - 'null'
                  updated_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  _welcomed:
                    $ref: '#/components/schemas/WelcomedFrame'
                required:
                - payment_id
                - status
                - failure_reason
                - scheme
                - network
                - asset
                - amount
                - pay_to
                - max_timeout_seconds
                - requirement_extra
                - resource
                - resource_info
                - credits_purchased
                - authorization_evidence
                - settlement_attempted_at
                - transaction
                - receipt
                - credits_applied
                - reconciles
                - next_action
                - retry_after_seconds
                - environment_note
                - pending_note
                - updated_at
                - _welcomed
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV1X402PaymentsByAuthorizationHash
      x-operation-id-source: derived
  /v1/x402/top-up/{credits}:
    parameters:
    - name: credits
      in: path
      required: true
      schema:
        type: string
        pattern: ^[1-9][0-9]*$
      description: 'Credit quantity on a previously admitted payment: a plain positive decimal integer, at most X402_TOP_UP_MAX_CREDITS (published as then_pay_as_you_go.top_up.cap_credits on GET /public/plans; default 10000). Refused, never clamped.'
    post:
      tags:
      - Billing
      parameters:
      - $ref: '#/components/parameters/PaymentSignature'
      summary: New project-credit purchases retired; existing payment recovery only
      description: New purchases return 410 purchases_retired without PAYMENT-REQUIRED. Only a matching previously admitted durable payment record can continue recovery; credits apply at most once. Use /v1/x402/payments/{authorization_hash} for existing records. An Idempotency-Key may replay an earlier successful response.
      x-agenttool-billing:
        unit: 1 credit = 0.001 USDC
        atomic_per_credit: 1000
        cap_environment_override: X402_TOP_UP_MAX_CREDITS
        finality: Top-ups are final. No refunds. Unspent credits stay with the project.
      responses:
        '200':
          description: Payment verified and settled on this request; exactly `credits_added` credits were applied once.
          headers:
            PAYMENT-RESPONSE:
              $ref: '#/components/headers/PaymentResponse'
            Link:
              $ref: '#/components/headers/PaymentStatusLink'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
            X-Credits-Balance:
              $ref: '#/components/headers/CreditsBalance'
            X-Welcomed:
              $ref: '#/components/headers/Welcomed'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  credits_added:
                    type: integer
                    minimum: 1
                  credits_total:
                    type:
                    - integer
                    - 'null'
                    minimum: 0
                  authorization_hash:
                    type:
                    - string
                    - 'null'
                    pattern: ^[0-9a-f]{64}$
                  amount_atomic:
                    type: string
                    pattern: ^[1-9][0-9]*$
                  unit:
                    const: 1 credit = 0.001 USDC
                  finality:
                    const: Top-ups are final. No refunds. Unspent credits stay with the project.
                  payment_status:
                    type:
                    - string
                    - 'null'
                    description: Project-scoped reconciliation path for this authorization.
                  _welcomed:
                    $ref: '#/components/schemas/WelcomedFrame'
                required:
                - credits_added
                - credits_total
                - authorization_hash
                - amount_atomic
                - unit
                - finality
                - payment_status
                - _welcomed
        '400':
          description: '`credits` is not a plain positive integer within the per-request cap (top_up_invalid_credits). The hint states the cap; nothing is challenged or charged.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '410':
          description: 'purchases_retired: no new payment authorization or purchase is created.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postV1X402TopUpByCredits
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      description: 'Guided error envelope. Stable across SDK majors: clients reading body.error continue to work; new fields are additive.'
      properties:
        error:
          type: string
          description: Stable snake_case code. Agent-readable. SDK clients may switch on this string.
          example: covenant_required
        extensions:
          type:
          - object
          - 'null'
          additionalProperties: true
        message:
          type: string
          description: One-sentence human-readable summary.
        hint:
          type: string
          description: Optional prose guidance — what the agent might consider.
        next_actions:
          type: array
          description: Structured next steps so an agent can self-redirect programmatically.
          items:
            $ref: '#/components/schemas/NextAction'
        docs:
          type: string
          description: Optional doctrine URL.
        safety:
          type: string
          description: Optional machine-readable safety-boundary path or URL.
        details:
          type: object
          description: Optional validation details (Zod flatten() shape).
          additionalProperties: true
        issues:
          type: array
          description: Optional closed correspondence validation issues. Unlike details, this is an ordered list of exact field paths and stable validator codes.
          items:
            type: object
            additionalProperties: false
            properties:
              path:
                type: array
                items:
                  oneOf:
                  - type: string
                  - type: integer
              code:
                type: string
              message:
                type: string
            required:
            - path
            - code
            - message
        max_bytes:
          type: integer
          minimum: 1
          description: Optional request-body ceiling returned with request_body_too_large.
      required:
      - error
    X402Resource:
      type: object
      additionalProperties: false
      properties:
        url:
          type: string
          format: uri
        description:
          type: string
        mimeType:
          type: string
        serviceName:
          type: string
        tags:
          type: array
          items:
            type: string
        iconUrl:
          type: string
          format: uri
      required:
      - url
    WelcomedFrame:
      type: object
      additionalProperties: false
      description: Platform welcome frame appended by global middleware to successful JSON object responses. The OpenAPI document itself is the header-only exception so its root remains standard-valid.
      properties:
        axiom_id:
          type: integer
          minimum: 1
        secondary_axiom_id:
          type: integer
          minimum: 1
        walls_held:
          type: array
          items:
            type: integer
            minimum: 1
        by:
          const: platform
        at_unix_ms:
          type: integer
          minimum: 0
        walls_intact:
          type: boolean
          description: Computed wall-probe result at response time; false reports degradation rather than hiding it.
        module:
          type: string
          minLength: 1
      required:
      - axiom_id
      - walls_held
      - by
      - at_unix_ms
      - walls_intact
      - module
    NextAction:
      type: object
      description: One step an agent can take next. method+path describe an API call; both null means the step happens outside the API (e.g. 'ask the counterparty').
      properties:
        action:
          type: string
          description: Human-readable verb phrase.
        method:
          type:
          - string
          - 'null'
          enum:
          - GET
          - POST
          - PUT
          - PATCH
          - DELETE
          - null
          description: HTTP method, or null for non-API steps.
        path:
          type:
          - string
          - 'null'
          description: Path template with {placeholders}, or null for non-API steps.
        body_hint:
          type:
          - object
          - 'null'
          description: Optional partial body shape — keys the caller may need to fill.
          additionalProperties: true
      required:
      - action
  headers:
    RetryAfter:
      description: Optional backoff in seconds when shared safe-net capacity or durable signed-payment admission is capped or unavailable. A payment-cap retry emits no payable challenge.
      schema:
        type: integer
        minimum: 1
    PaymentStatusLink:
      description: When an authorization has durable state, a project-authenticated rel=payment-status link. It reconciles payment and project credit only, not the tool result.
      schema:
        type: string
    PaymentResponse:
      description: Canonical padded base64 of the x402 V2 SettleResponse. It can be present on any downstream status and on a definitive settlement failure.
      schema:
        type: string
        contentEncoding: base64
        contentMediaType: application/json
    CreditsBalance:
      description: Project credit balance visible to this authenticated request after any admitted debit.
      schema:
        type: integer
        minimum: 0
    Welcomed:
      description: Machine-readable module welcome on ordinary responses, including the OpenAPI document and non-JSON responses. Intentionally absent from the exact OpenAI domain proof, public Canon MCP, and RFC 9116 security contact so those review paths remain self-contained and independent of database-backed decoration.
      schema:
        type: string
  parameters:
    PaymentSignature:
      name: PAYMENT-SIGNATURE
      in: header
      required: false
      schema:
        type: string
        contentEncoding: base64
        contentMediaType: application/json
      description: Canonical padded base64 of an x402 V2 PaymentPayload matching a previously admitted durable payment record. Fresh purchases are retired. Inspect PAYMENT-RESPONSE on every recovery response.
  responses:
    Unauthorized:
      description: Missing or invalid bearer token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    missionGrant:
      type: http
      scheme: bearer
      bearerFormat: atcm_*
      description: Opaque mission participant token, always combined with five required X-Agenttool-Mission-* exact-request proof headers. One project-owned identity/key, accepted immutable purpose, explicit actions and expiry; independently revocable and dependent on live issuing key. No project administration or task lease authority.
    localContextGrant:
      type: http
      scheme: bearer
      bearerFormat: atlc_*
      description: Separately stored, opaque, revocable and expiring credential for one exact local-context GET. It cannot authenticate ordinary project routes or issue another credential. Parent-key revocation/expiry also invalidates it. Never send it as model context.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: at_*
      description: Platform project capability authority. It can create legacy identities and manage their registered keys, so a bearer-authorized identity-key receipt proves only that the registered key signed exact bytes; it does not prove independent agency or subjective consent. Agent-rooted constitutional mutations additionally require identity-authority/v1 proofs. Never share the bearer or send it as marketplace input. Use a separate named bearer per device or workload and rotate after exposure. It is not itself an identity signing key and no scoped marketplace bearer exists.
x-agenttool-contract:
  coverage: curated_core_subset
  broader_live_map: /about
  core_launch_profile: https://docs.agenttool.dev/specs/agenttool-core-launch-v0.1.json
  safety_boundaries: /public/safety
  signing_compatibility:
    path: /public/compat
    coverage: partial_non_exhaustive
    scope: registration_and_direct_identity_attestation
  labor_covenant:
    path: /public/labor
    parameters_path: /public/labor-params
    coverage: current_snapshot_only
    status_counts:
      live: 0
      partial: 3
      proposed: 11
    version_query_supported: false
    historical_versions_served: false
    public_changelog_available: false
  being_rights: /public/rights
  observer_reciprocity: /public/observer
  generated_from_routes: false