Merit Systems Payments API

openapi: 3.1.0
info:
  title: AgentCash Balances Payments API
  description: Wallet management, search, and payment APIs for AgentCash.
  version: 0.1.2
  x-guidance: 'AgentCash exposes SIWX and paid endpoints for wallet-connected agents.


    ## SIWX endpoints (free, wallet identity required)

    - POST /api/search — search for relevant API origins by natural language query

    - POST /api/invite-codes — manage invite codes

    - POST /api/organizations — manage organizations


    ## Paid endpoints (x402 or MPP)

    - POST /api/send — send USDC on Base or Solana


    Registration is handled directly by x402scan (POST /api/x402/registry/register-origin) and mppscan (POST /api/mpp/register).'
  guidance: 'AgentCash exposes SIWX and paid endpoints for wallet-connected agents.


    ## SIWX endpoints (free, wallet identity required)

    - POST /api/search — search for relevant API origins by natural language query

    - POST /api/invite-codes — manage invite codes

    - POST /api/organizations — manage organizations


    ## Paid endpoints (x402 or MPP)

    - POST /api/send — send USDC on Base or Solana


    Registration is handled directly by x402scan (POST /api/x402/registry/register-origin) and mppscan (POST /api/mpp/register).'
  contact:
    name: Merit Systems
    url: https://merit.systems
servers:
- url: https://agentcash.dev
tags:
- name: Payments
paths:
  /user/{user_id}/payments:
    get:
      operationId: getPaymentsBySender
      summary: Get paginated user payments sent by the user
      tags:
      - Payments
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: integer
      - name: group_id
        in: query
        required: false
        description: Filter by specific group ID (UUID)
        schema:
          type: string
          format: uuid
      - name: page_size
        in: query
        required: false
        description: 'Maximum number of results to return (default: 50, max: 100)'
        schema:
          type: integer
          default: 50
          maximum: 100
      - name: page
        in: query
        required: false
        description: 'Page number for pagination (default: 1)'
        schema:
          type: integer
          default: 1
      responses:
        '200':
          description: Paginated outgoing payments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedOutgoingPayments'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    OutgoingPayment:
      type: object
      properties:
        type:
          type: string
          enum:
          - UserPayment
          - RepoFund
        sender_id:
          type: integer
        recipient_id:
          type: integer
          description: Present for UserPayment
        repo_id:
          type: integer
          description: Present for RepoFund
        amount:
          $ref: '#/components/schemas/Amount'
        token:
          type: string
        timestamp:
          type: string
          format: date-time
        tx_hash:
          type: string
        group_id:
          type: string
        claim_status:
          type: string
          enum:
          - Claimed
          - Deposited
          - Reclaimed
        claim_deadline:
          type: string
          format: date-time
      required:
      - type
      - sender_id
      - amount
      - token
      - timestamp
      - tx_hash
    Amount:
      type: object
      properties:
        raw:
          type: string
        formatted:
          type: string
      required:
      - raw
      - formatted
    Error:
      type: object
      description: Standard error envelope returned on non-2xx responses.
      properties:
        status:
          type: integer
        message:
          type: string
        request_id:
          type: string
      required:
      - status
      - message
    PaginatedOutgoingPayments:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/OutgoingPayment'
        page_size:
          type: integer
        page:
          type: integer
        total_count:
          type: integer
        has_next:
          type: boolean
      required:
      - items
      - page_size
      - page
      - total_count
      - has_next
  responses:
    Unauthorized:
      description: Invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    siwx:
      type: apiKey
      in: header
      name: SIGN-IN-WITH-X