openapi: 3.1.0
info:
  title: AgentCell API
  version: 0.1.0
  description: Backend REST API for AgentCell (customer /v1, admin /v1/admin, device /v1/device)
servers:
  - url: https://api.agentcell.store
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
  schemas:
    PaymentDetails:
      type: object
      required: [amount_usd, currency, intent, rails]
      properties:
        amount_usd:
          type: string
          example: "148.00"
        currency:
          type: string
          example: USD
        intent:
          type: string
          enum: [setup, renewal, top_up, reinstate, create_cell]
        tier:
          type: string
        cell_id:
          type: string
        rails:
          type: array
          items:
            type: string
            enum: [stripe, x402, mpp]
        checkout_url:
          type: string
          format: uri
        x402:
          $ref: "#/components/schemas/X402Requirements"
        mpp:
          type: object
          additionalProperties: true
    X402Quote:
      type: object
      required: [network, caip2_network, asset, pay_to]
      properties:
        network:
          type: string
          enum: [base, solana]
          description: Human-readable network id
        caip2_network:
          type: string
          description: CAIP-2 chain id (e.g. eip155:8453, solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)
          examples:
            - eip155:8453
            - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
        asset:
          type: string
          example: USDC
        pay_to:
          type: string
          description: Stripe crypto deposit address (seller receive), not CDP agent wallet
          examples:
            - "0x915b8e625e00124ad83090e8195ecd4e034dc465"
            - uFMFdsHRwuTgeqmSV8K9bFFQwzmbxYKkDgAH6ub2ni1
        contract:
          type: string
          description: Base USDC contract address (Base rail only)
          example: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
        mint:
          type: string
          description: Solana USDC mint (Solana rail only)
          example: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
        deposit_address_id:
          type: string
          description: Stripe crypto deposit address id (cda_...)
    X402Requirements:
      type: object
      required: [schemes, networks, accepted_networks, quotes, asset]
      properties:
        schemes:
          type: array
          items:
            type: string
          example: [exact]
        networks:
          type: array
          description: Configured seller networks (dual-rail when Base + Solana payTo configured)
          items:
            type: string
            enum: [base, solana]
          example: [base, solana]
        accepted_networks:
          type: array
          items:
            type: string
            enum: [base, solana]
        quotes:
          type: array
          items:
            $ref: "#/components/schemas/X402Quote"
        asset:
          type: string
          example: USDC
        pay_to:
          type: string
          description: Present when exactly one network is quoted (single-rail filter)
        network:
          type: string
          description: CAIP-2 network when exactly one quote is returned
    X402Wallet:
      type: object
      required: [wallet_id, organization_id, network, address, created_at]
      properties:
        wallet_id:
          type: string
          example: x4w_abc123
        organization_id:
          type: string
        network:
          type: string
          enum: [base, solana]
        address:
          type: string
          description: Agent payer wallet registered for org (not seller payTo)
        label:
          type: string
        created_at:
          type: string
          format: date-time
    CreateX402WalletRequest:
      type: object
      required: [network, address]
      properties:
        network:
          type: string
          enum: [base, solana]
        address:
          type: string
        label:
          type: string
    X402WalletList:
      type: object
      required: [wallets]
      properties:
        wallets:
          type: array
          items:
            $ref: "#/components/schemas/X402Wallet"
    PaymentOptions:
      type: object
      properties:
        rails:
          type: array
          items:
            type: string
        prepaid_balance_usd:
          type: number
        min_amount_usd:
          type: number
        x402:
          $ref: "#/components/schemas/X402Requirements"
        mpp:
          type: object
          additionalProperties: true
        stripe:
          type: object
          additionalProperties: true
paths:
  /health:
    get:
      summary: Health check
      responses:
        "200":
          description: OK
  /v1/agent/sign-up:
    post:
      summary: Register organization
  /v1/agent/verify:
    post:
      summary: Verify OTP
  /v1/cells:
    get:
      summary: List cells
    post:
      summary: Create cell
  /v1/cells/{cell_id}/messages:
    get:
      summary: List messages for cell
      security:
        - bearerAuth: []
      parameters:
        - name: cell_id
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: Message list
  /v1/cells/{cell_id}/messages/send:
    post:
      summary: Send message
      security:
        - bearerAuth: []
      parameters:
        - name: cell_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [to, body]
              properties:
                to:
                  type: string
                body:
                  type: string
                media_urls:
                  type: array
                  items:
                    type: string
                    format: uri
      responses:
        "202":
          description: Message accepted
  /v1/billing/status:
    get:
      summary: Billing status
  /v1/billing/payment-options:
    get:
      summary: Available payment rails and x402 multi-network quotes
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Payment options
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentOptions"
  /v1/billing/checkout:
    post:
      summary: Stripe checkout
  /v1/billing/x402/requirements:
    get:
      summary: x402 payment quote (Base + Solana dual-rail when configured)
      security:
        - bearerAuth: []
      parameters:
        - name: intent
          in: query
          required: true
          schema:
            type: string
            enum: [setup, renewal, top_up, reinstate, create_cell]
        - name: tier
          in: query
          schema:
            type: string
        - name: cell_id
          in: query
          schema:
            type: string
        - name: amount_usd
          in: query
          schema:
            type: number
        - name: network
          in: query
          description: Filter to base or solana (single-rail quote)
          schema:
            type: string
            enum: [base, solana]
      responses:
        "200":
          description: Payment details with x402 requirements
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentDetails"
  /v1/billing/x402/wallets:
    get:
      summary: List org-linked agent payer wallets
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Registered x402 wallets
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/X402WalletList"
    post:
      summary: Register agent payer wallet for org
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateX402WalletRequest"
      responses:
        "201":
          description: Wallet registered
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/X402Wallet"
  /v1/billing/x402/wallets/{wallet_id}:
    delete:
      summary: Remove linked x402 wallet
      security:
        - bearerAuth: []
      parameters:
        - name: wallet_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Wallet removed
  /v1/billing/mpp/pay:
    post:
      summary: MPP payment
  /v1/pods:
    get:
      summary: List pods
    post:
      summary: Create pod
  /v1/agent/status:
    get:
      summary: Agent observability status
  /.well-known/mpp:
    get:
      summary: MPP discovery document
  /.well-known/oauth-authorization-server:
    get:
      summary: OAuth 2.0 authorization server metadata (RFC 8414)
  /oauth/authorize:
    get:
      summary: OAuth authorization redirect to console consent
  /oauth/token:
    post:
      summary: OAuth token endpoint (authorization_code, refresh_token)
  /oauth/introspect:
    post:
      summary: OAuth token introspection
  /oauth/revoke:
    post:
      summary: OAuth token revocation
  /v1/oauth/consent:
    post:
      summary: Approve OAuth consent with verified API key
  /v1/oauth/consent/session:
    post:
      summary: Approve OAuth consent with console session
