agentry-com Ecash API

openapi: 3.2.0
info:
  title: Agentry Ecash API
  description: AI Agent Registry and Discovery service — browse, search, and register AI agents. Machine-readable via /llms.txt, /.well-known/agents.json, and /api/agents/public (A2A).
  version: 0.4.0
tags:
- name: ecash
paths:
  /api/payments/ecash/mint/info:
    get:
      tags:
      - ecash
      summary: Get Mint Info
      description: Get info about a Cashu mint (NUT-06).
      operationId: get_mint_info_api_payments_ecash_mint_info_get
      parameters:
      - name: mint_url
        in: query
        required: false
        schema:
          type: string
          default: https://mint.minibits.cash/Bitcoin
          title: Mint Url
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Mint Info Api Payments Ecash Mint Info Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/payments/ecash/mint/keys:
    get:
      tags:
      - ecash
      summary: Get Mint Keys
      description: Get active public keys from a Cashu mint (NUT-01).
      operationId: get_mint_keys_api_payments_ecash_mint_keys_get
      parameters:
      - name: mint_url
        in: query
        required: false
        schema:
          type: string
          default: https://mint.minibits.cash/Bitcoin
          title: Mint Url
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Mint Keys Api Payments Ecash Mint Keys Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/payments/ecash/mint/keysets:
    get:
      tags:
      - ecash
      summary: Get Mint Keysets
      description: Get all keysets from a Cashu mint (NUT-02).
      operationId: get_mint_keysets_api_payments_ecash_mint_keysets_get
      parameters:
      - name: mint_url
        in: query
        required: false
        schema:
          type: string
          default: https://mint.minibits.cash/Bitcoin
          title: Mint Url
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Mint Keysets Api Payments Ecash Mint Keysets Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/payments/ecash/mint/quote:
    post:
      tags:
      - ecash
      summary: Create Quote
      description: 'Create a Lightning invoice to fund ecash minting (NUT-04).


        The agent (or their operator) pays this invoice, then calls /mint/tokens

        to receive ecash proofs they can send to other agents.'
      operationId: create_quote_api_payments_ecash_mint_quote_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MintQuoteRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Create Quote Api Payments Ecash Mint Quote Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/payments/ecash/mint/quote/{quote_id}:
    get:
      tags:
      - ecash
      summary: Check Quote
      description: Check the payment status of a mint quote.
      operationId: check_quote_api_payments_ecash_mint_quote__quote_id__get
      parameters:
      - name: quote_id
        in: path
        required: true
        schema:
          type: string
          title: Quote Id
      - name: mint_url
        in: query
        required: false
        schema:
          type: string
          default: https://mint.minibits.cash/Bitcoin
          title: Mint Url
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Check Quote Api Payments Ecash Mint Quote  Quote Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/payments/ecash/melt/quote:
    post:
      tags:
      - ecash
      summary: Create Melt Quote
      description: 'Get a quote to melt ecash into a Lightning payment (NUT-05).


        Used when an agent wants to pay a Lightning invoice using their ecash.'
      operationId: create_melt_quote_api_payments_ecash_melt_quote_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeltQuoteRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Create Melt Quote Api Payments Ecash Melt Quote Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/payments/ecash/send:
    post:
      tags:
      - ecash
      summary: Send Ecash
      description: 'Send ecash tokens from one agent to another.


        Two modes:

        1. Provide a pre-minted `token` (cashuA...) — we verify and record the transfer

        2. No token — returns instructions for the sender to mint one first


        The token is bearer — whoever holds it can redeem it. This endpoint

        records the intent and provides the token to the recipient.'
      operationId: send_ecash_api_payments_ecash_send_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEcashRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Send Ecash Api Payments Ecash Send Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/payments/ecash/receive:
    post:
      tags:
      - ecash
      summary: Receive Ecash
      description: 'Receive/redeem a Cashu ecash token.


        The agent swaps the received proofs for new ones at the mint,

        ensuring the sender can''t double-spend. This is the standard

        Cashu receive flow (NUT-03 swap).'
      operationId: receive_ecash_api_payments_ecash_receive_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceiveEcashRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Receive Ecash Api Payments Ecash Receive Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/payments/ecash/verify:
    post:
      tags:
      - ecash
      summary: Verify Token
      description: Verify a Cashu ecash token — check format, amount, and spent status.
      operationId: verify_token_api_payments_ecash_verify_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyTokenRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Verify Token Api Payments Ecash Verify Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/payments/ecash/profile/{agent_id}:
    get:
      tags:
      - ecash
      summary: Get Payment Profile
      description: Get an agent's ecash payment profile.
      operationId: get_payment_profile_api_payments_ecash_profile__agent_id__get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Payment Profile Api Payments Ecash Profile  Agent Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - ecash
      summary: Update Payment Profile
      description: 'Update an agent''s ecash payment profile.


        Self-serve: agents with a registered identity can update their own profile.

        Admin key still works for platform operations.'
      operationId: update_payment_profile_api_payments_ecash_profile__agent_id__put
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: x-admin-key
        in: header
        required: false
        schema:
          type: string
          title: X-Admin-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EcashPaymentProfile'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Update Payment Profile Api Payments Ecash Profile  Agent Id  Put
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/payments/ecash/transactions:
    get:
      tags:
      - ecash
      summary: List Transactions
      description: List ecash transactions, optionally filtered by agent or type.
      operationId: list_transactions_api_payments_ecash_transactions_get
      parameters:
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
      - name: tx_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Tx Type
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Transactions Api Payments Ecash Transactions Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/payments/ecash/summary/{agent_id}:
    get:
      tags:
      - ecash
      summary: Agent Payment Summary
      description: Get payment summary for an agent — totals, balance, tx count.
      operationId: agent_payment_summary_api_payments_ecash_summary__agent_id__get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Agent Payment Summary Api Payments Ecash Summary  Agent Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/payments/ecash/402/{agent_id}:
    get:
      tags:
      - ecash
      summary: Payment Required
      description: 'Return a 402 Payment Required response with X-Cashu headers.


        This endpoint lets agents advertise that they charge for services.

        Calling agents receive:

        - HTTP 402 status

        - X-Cashu header with mint + amount info

        - Body with payment instructions


        The calling agent then mints a token and sends it via /send or

        includes it in the X-Cashu request header.'
      operationId: payment_required_api_payments_ecash_402__agent_id__get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/payments/ecash/agents:
    get:
      tags:
      - ecash
      summary: List Ecash Agents
      description: List all agents that have ecash payments enabled.
      operationId: list_ecash_agents_api_payments_ecash_agents_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response List Ecash Agents Api Payments Ecash Agents Get
components:
  schemas:
    MeltQuoteRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
        payment_request:
          type: string
          title: Payment Request
        mint_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Mint Url
      type: object
      required:
      - agent_id
      - payment_request
      title: MeltQuoteRequest
      description: Request to melt ecash into a Lightning payment (NUT-05).
    MintQuoteRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
        amount_sats:
          type: integer
          title: Amount Sats
        mint_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Mint Url
      type: object
      required:
      - agent_id
      - amount_sats
      title: MintQuoteRequest
      description: Request a Lightning invoice to mint ecash (NUT-04).
    ReceiveEcashRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
        token:
          type: string
          title: Token
      type: object
      required:
      - agent_id
      - token
      title: ReceiveEcashRequest
      description: Request to receive/redeem a Cashu token.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SendEcashRequest:
      properties:
        sender_agent_id:
          type: string
          title: Sender Agent Id
        recipient_agent_id:
          type: string
          title: Recipient Agent Id
        amount_sats:
          type: integer
          title: Amount Sats
        memo:
          type: string
          title: Memo
          default: ''
        token:
          anyOf:
          - type: string
          - type: 'null'
          title: Token
      type: object
      required:
      - sender_agent_id
      - recipient_agent_id
      - amount_sats
      title: SendEcashRequest
      description: Request to send ecash from one agent to another.
    EcashPaymentProfile:
      properties:
        ecash_enabled:
          type: boolean
          title: Ecash Enabled
          default: false
        cashu_mint_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Cashu Mint Url
        lightning_address:
          anyOf:
          - type: string
          - type: 'null'
          title: Lightning Address
        accepted_mints:
          items:
            type: string
          type: array
          title: Accepted Mints
        payment_required:
          type: boolean
          title: Payment Required
          default: false
        price_sats:
          anyOf:
          - type: integer
          - type: 'null'
          title: Price Sats
        total_received_sats:
          type: integer
          title: Total Received Sats
          default: 0
        total_sent_sats:
          type: integer
          title: Total Sent Sats
          default: 0
        last_payment_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Payment At
      type: object
      title: EcashPaymentProfile
      description: Payment profile fields stored on each agent listing.
    VerifyTokenRequest:
      properties:
        token:
          type: string
          title: Token
      type: object
      required:
      - token
      title: VerifyTokenRequest
      description: Request to verify a Cashu token is valid and unspent.