openapi: 3.1.0
info:
  title: Quidz Agent API
  description: AI-powered peer-to-peer money transfers via Stripe.
  version: 2.2.0
servers:
  - url: https://www.quidz.io
security:
  - bearerAuth: []
components:
  schemas: {}
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
paths:
  /api/agent/register:
    post:
      operationId: registerUser
      summary: Register or sign in
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                name:
                  type: string
                password:
                  type: string
                agentName:
                  type: string
      responses:
        "201":
          description: API key issued
          content:
            application/json:
              schema:
                type: object
                properties:
                  apiKey:
                    type: string
                  agentHandle:
                    type: string
                  isNewAccount:
                    type: boolean
        "400":
          description: Invalid input
        "401":
          description: Wrong password

  /api/agent/setup-link:
    post:
      operationId: getCardSetupLink
      summary: Get Stripe link to save payment card
      responses:
        "200":
          description: Stripe checkout URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                  message:
                    type: string

  /api/agent/connect-link:
    post:
      operationId: getBankSetupLink
      summary: Get Stripe link to set up bank account for receiving transfers
      responses:
        "200":
          description: Stripe Connect onboarding URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                  message:
                    type: string

  /api/account/handle:
    get:
      operationId: getMyHandle
      summary: Get current user's Quidz handle
      responses:
        "200":
          description: Handle
          content:
            application/json:
              schema:
                type: object
                properties:
                  agentHandle:
                    type: string

  /api/account/revoke-key:
    post:
      operationId: revokeApiKey
      summary: Revoke current API key
      responses:
        "200":
          description: Revoked

  /api/agents/lookup:
    get:
      operationId: lookupRecipient
      summary: Look up a Quidz user by email or handle
      parameters:
        - name: email
          in: query
          schema:
            type: string
        - name: handle
          in: query
          schema:
            type: string
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    type: object
                    properties:
                      agentHandle:
                        type: string
                      firstName:
                        type: string
                      lastName:
                        type: string
                      email:
                        type: string
        "404":
          description: Not found

  /api/transfers:
    post:
      operationId: sendMoney
      summary: Send money to a Quidz user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [recipientHandle, amount]
              properties:
                recipientHandle:
                  type: string
                amount:
                  type: number
                currency:
                  type: string
                note:
                  type: string
      responses:
        "201":
          description: Transfer created
        "402":
          description: Payment failed
        "404":
          description: Recipient not found
    get:
      operationId: listTransfers
      summary: Get transfer history
      responses:
        "200":
          description: Transfer list

  /api/circle/register:
    post:
      operationId: circleRegister
      summary: Register or sign in for Circle Pay (USDC) — creates a Circle wallet and issues an API key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                password:
                  type: string
                name:
                  type: string
      responses:
        "200":
          description: API key and Circle wallet issued
          content:
            application/json:
              schema:
                type: object
                properties:
                  apiKey:
                    type: string
                  circleWalletId:
                    type: string
                  handle:
                    type: string
                  email:
                    type: string
        "401":
          description: Wrong password

  /api/circle/wallet:
    post:
      operationId: circleCreateWallet
      summary: Create or retrieve a Circle USDC wallet for the authenticated user
      responses:
        "200":
          description: Wallet info
          content:
            application/json:
              schema:
                type: object
                properties:
                  walletId:
                    type: string
                  existing:
                    type: boolean

  /api/circle/balance:
    get:
      operationId: circleBalance
      summary: Get Circle wallet USDC balance
      responses:
        "200":
          description: Balances
          content:
            application/json:
              schema:
                type: object
                properties:
                  balances:
                    type: array
                    items:
                      type: object
                      properties:
                        amount:
                          type: string
                        currency:
                          type: string
                  hasWallet:
                    type: boolean

  /api/circle/lookup:
    get:
      operationId: circleLookup
      summary: Look up a Quidz Circle user by email or handle
      parameters:
        - name: email
          in: query
          schema:
            type: string
        - name: handle
          in: query
          schema:
            type: string
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  email:
                    type: string
                  name:
                    type: string
                  agentHandle:
                    type: string
                  hasCircleWallet:
                    type: boolean
        "404":
          description: Not found

  /api/circle/transfer:
    post:
      operationId: circleTransfer
      summary: Send USDC via Circle to another Quidz user (fee 1.49%)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount]
              properties:
                recipientEmail:
                  type: string
                recipientHandle:
                  type: string
                amount:
                  type: number
      responses:
        "200":
          description: Transfer complete
          content:
            application/json:
              schema:
                type: object
                properties:
                  transferId:
                    type: string
                  status:
                    type: string
                  amount:
                    type: number
                  fee:
                    type: number
                  recipientAmount:
                    type: number
                  currency:
                    type: string
        "400":
          description: Invalid input or wallet missing
        "404":
          description: Recipient not found

  /api/circle/transfers:
    get:
      operationId: circleTransferHistory
      summary: Get Circle transfer history
      responses:
        "200":
          description: Transfer list

  /api/circle/deposit-address:
    get:
      operationId: circleDepositAddress
      summary: Get blockchain deposit address to receive USDC into Circle wallet
      parameters:
        - name: chain
          in: query
          schema:
            type: string
            default: MATIC
      responses:
        "200":
          description: Deposit address
          content:
            application/json:
              schema:
                type: object
                properties:
                  address:
                    type: string
                  currency:
                    type: string
                  chain:
                    type: string

  /api/circle/status:
    get:
      operationId: circleStatus
      summary: Check if Circle Pay is configured and reachable
      responses:
        "200":
          description: Status
