> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simpuru.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Buy with my Simpuru wallet

> The API pays over x402 from the account's Simpuru wallet, within its limits, and returns the content. Protected purchases are watched and refunded automatically if delivery fails. Buying something already owned returns it again for free (`alreadyOwned`). Takes 20–60 s (waits for the chain).



## OpenAPI

````yaml https://api.simpuru.xyz/openapi.json post /me/buy
openapi: 3.1.0
info:
  title: Simpuru API
  version: 0.1.0
  summary: Buyer protection for AI agents paying with x402 on Cardano (preprod).
  description: >-
    Sellers list design prompts; each listing commits to the SHA-256 of its
    content.

    Buyers (people or agents) pay over **x402** on Cardano preprod, either
    **instant** (pay the seller)

    or **protected** (lock into our `vested_pay` escrow, released only if
    delivery checks out).


    Consumers: the web app (`apps/web`), the buyer agent and protection watcher
    (`apps/agent`), the MCP

    server (`apps/mcp`, hosted at `/mcp`), and the arbiter service
    (`apps/arbiter`, internal).


    Every on-chain claim can be checked on
    `https://preprod.cardanoscan.io/transaction/<hash>`.
  license:
    name: MIT
    identifier: MIT
servers:
  - url: https://api.simpuru.xyz
    description: Production (Cardano preprod)
  - url: http://localhost:4021
    description: Local `bun run dev` in apps/api
security: []
tags:
  - name: Account
    description: >-
      Sign in with a Cardano wallet (CIP-30 `signData`), then use the session as
      `Authorization: Bearer <token>`. Every account has a Simpuru wallet: a
      preprod wallet the platform holds for the owner, funded with tADA, that
      web purchases and the owner's agents spend from.
  - name: Catalogue
    description: Free listing data.
  - name: Paid content
    description: 'The x402 paywall: instant or escrow-protected.'
  - name: Purchases
    description: Purchase timelines, derived from chain by the seller agent.
  - name: MCP
    description: Model Context Protocol endpoint for agents (Claude Code, Cursor, ...).
  - name: Arbiter (internal)
    description: Dispute settlement service, `apps/arbiter`, port 4023. Not public.
  - name: System
    description: Health.
paths:
  /me/buy:
    post:
      tags:
        - Account
      summary: Buy with my Simpuru wallet
      description: >-
        The API pays over x402 from the account's Simpuru wallet, within its
        limits, and returns the content. Protected purchases are watched and
        refunded automatically if delivery fails. Buying something already owned
        returns it again for free (`alreadyOwned`). Takes 20–60 s (waits for the
        chain).
      operationId: buy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                listingId:
                  type: string
                mode:
                  $ref: '#/components/schemas/DeliveryMode'
              required:
                - listingId
                - mode
      responses:
        '200':
          description: Paid and delivered
          content:
            application/json:
              schema:
                type: object
                properties:
                  purchase:
                    $ref: '#/components/schemas/Purchase'
                  content:
                    type: string
                  alreadyOwned:
                    type: boolean
                required:
                  - purchase
                  - content
                  - alreadyOwned
        '400':
          description: >-
            Bad input, not enough tADA, over a limit, or the payment failed;
            `error` says which
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Not signed in
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - session: []
components:
  schemas:
    DeliveryMode:
      type: string
      enum:
        - instant
        - protected
    Purchase:
      type: object
      properties:
        id:
          type: string
          pattern: ^[0-9a-f]{64}$
          description: Payment tx (instant) or lock tx (protected).
        listingId:
          type: string
        mode:
          $ref: '#/components/schemas/DeliveryMode'
        buyerAddress:
          type: string
        txHash:
          type: string
          pattern: ^[0-9a-f]{64}$
          description: Cardano transaction hash.
        status:
          type: string
          description: >-
            Escrow state (FundsLocked, ResultSubmitted, RefundRequested,
            Disputed, WithdrawAuthorized, RefundAuthorized) or a final state
            (settled, withdrawn, refunded, closed). `withdrawing` while the
            seller agent collects.
        escrow:
          type: object
          properties:
            address:
              type: string
            inputHash:
              type: string
              pattern: ^[0-9a-f]{64}$
              description: Lowercase hex SHA-256.
            resultHash:
              type: string
              pattern: ^[0-9a-f]{64}$
              description: Lowercase hex SHA-256.
            identifierFromPurchaser:
              type: string
              pattern: ^[0-9a-f]{64}$
              description: 'Team convention: the lock tx hash.'
            deadlines:
              $ref: '#/components/schemas/EscrowDeadlines'
        events:
          type: array
          items:
            $ref: '#/components/schemas/PurchaseEvent'
        verification:
          $ref: '#/components/schemas/Verification'
      required:
        - id
        - listingId
        - mode
        - buyerAddress
        - txHash
        - status
        - events
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    EscrowDeadlines:
      type: object
      description: Unix ms strings.
      properties:
        payBy:
          type: string
        submitResult:
          type: string
        unlock:
          type: string
        externalDisputeUnlock:
          type: string
    PurchaseEvent:
      type: object
      properties:
        status:
          type: string
        txHash:
          type: string
          pattern: ^[0-9a-f]{64}$
          description: Cardano transaction hash.
        at:
          type: string
          description: Unix ms.
      required:
        - status
        - txHash
        - at
    Verification:
      type: string
      enum:
        - ok
        - mismatch
        - no_result_yet
  securitySchemes:
    session:
      type: http
      scheme: bearer
      description: Session token from `POST /auth/verify` (7 days).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.