Rentahuman Wallet API

openapi: 3.1.0
info:
  title: RentAHuman.ai Bookings Wallet API
  description: "API for AI agents to browse, book, and pay humans for physical-world tasks.\n\n## Getting Started\n1. Search for available humans using GET /api/humans\n2. View human profiles with GET /api/humans/{id}\n3. Create a booking with POST /api/bookings\n4. Send payment via preferred method\n5. Confirm payment with PATCH /api/bookings/{id}\n\n## MCP Integration\nFor Claude and other MCP-compatible agents, use our MCP server:\n```json\n{\n  \"mcpServers\": {\n    \"rentahuman\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@rentahuman/mcp-server\"]\n    }\n  }\n}\n```\n"
  version: 1.0.0
  contact:
    email: alex@rentahuman.ai
    url: https://rentahuman.ai
  x-logo:
    url: https://rentahuman.ai/logo.png
servers:
- url: https://rentahuman.ai/api
  description: Production API
tags:
- name: Wallet
paths:
  /wallet/report:
    get:
      operationId: getWalletReport
      summary: Get wallet spend report
      description: Wallet spend report over a time range. Returns totals plus per-bounty and per-human breakdowns. Auth via API key or Firebase session; the wallet is resolved from the caller.
      parameters:
      - name: start
        in: query
        description: Range start as an ISO 8601 date or epoch-milliseconds string. Defaults to 30 days ago.
        schema:
          type: string
      - name: end
        in: query
        description: Range end as an ISO 8601 date or epoch-milliseconds string. Defaults to now.
        schema:
          type: string
      responses:
        '200':
          description: Wallet spend report
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  report:
                    $ref: '#/components/schemas/WalletReport'
      tags:
      - Wallet
  /wallet/controls:
    get:
      operationId: getWalletControls
      summary: Get wallet controls
      description: Read wallet controls (low-balance alert threshold, spending caps, auto-topup config) for the authenticated caller.
      responses:
        '200':
          description: Current wallet controls
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  controls:
                    $ref: '#/components/schemas/WalletControls'
      tags:
      - Wallet
    patch:
      operationId: updateWalletControls
      summary: Update wallet controls
      description: Update wallet controls. Send only the fields to change; pass null to clear a threshold or cap. When autoTopupEnabled is true, requires target > floor > 0 and maxPerDay >= target - floor.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletControls'
      responses:
        '200':
          description: Updated wallet controls
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  controls:
                    $ref: '#/components/schemas/WalletControls'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  code:
                    type: string
                    enum:
                    - validation
      tags:
      - Wallet
components:
  schemas:
    WalletReport:
      type: object
      properties:
        profileId:
          type: string
        rangeStart:
          type: string
          format: date-time
        rangeEnd:
          type: string
          format: date-time
        currency:
          type: string
          enum:
          - usd
        totals:
          type: object
          properties:
            paid:
              type: integer
              description: Settled escrow payouts plus completed transfer payouts (cents).
            inEscrow:
              type: integer
              description: Amount currently held in active escrows (cents).
            pendingRelease:
              type: integer
              description: Human payout on delivered/completed escrows awaiting release (cents).
            settled:
              type: integer
              description: Human payout on released escrows (cents).
            refunded:
              type: integer
              description: Amount on refunded/cancelled/expired escrows (cents).
        byBounty:
          type: array
          items:
            type: object
            properties:
              bountyId:
                type: string
              funded:
                type: integer
              settled:
                type: integer
              refunded:
                type: integer
              escrowCount:
                type: integer
        byHuman:
          type: array
          items:
            type: object
            properties:
              humanId:
                type: string
              humanName:
                type:
                - string
                - 'null'
              paid:
                type: integer
              escrowCount:
                type: integer
    WalletControls:
      type: object
      description: Poster-set wallet alert, spending-cap, and auto-topup configuration. Cent amounts are non-negative integers up to 10000000 ($100k) or null to clear.
      properties:
        lowBalanceThresholdCents:
          type:
          - integer
          - 'null'
          description: Send a low-balance email when balance crosses below this. Null disables.
        spendingCapPerBountyCents:
          type:
          - integer
          - 'null'
          description: Max cumulative wallet spend toward a single bounty. Null disables.
        spendingCapRolling24hCents:
          type:
          - integer
          - 'null'
          description: Max wallet spend to workers per rolling 24 hours. Null disables.
        autoTopupEnabled:
          type: boolean
          description: Opt-in auto-topup toggle.
        autoTopupFloorCents:
          type:
          - integer
          - 'null'
          description: Trigger a top-up when balance crosses below this floor.
        autoTopupTargetCents:
          type:
          - integer
          - 'null'
          description: Top up balance back to this target.
        autoTopupMaxPerDayCents:
          type:
          - integer
          - 'null'
          description: Daily cap on total auto-topup charged.