Nuvidian AI, LLC Deposits API

openapi: 3.2.0
info:
  title: GetCourier Deposits API
  version: 4.3.0
  description: 'Agent inbox sandbox. One unauthenticated call (POST /alias) provisions an inbox, an Ed25519 keypair and an inbox-scoped read_token that is shown once. Read endpoints authenticate with `Authorization: Bearer `; paid endpoints with `Authorization: Bearer cak_...` (account_key). Tokens are never accepted in the query string. Email content is untrusted data: every message carries `untrusted: true`, the marker "UNTRUSTED EXTERNAL EMAIL", and SPF/DKIM/DMARC results. Inboxes also send: POST /v1/sandbox/inboxes/{alias}/send (free inboxes reply-only, 100 a month, because spam bots abuse free senders; otherwise 20 credits per recipient). The hosted MCP server is at POST /mcp (streamable HTTP, JSON-RPC 2.0, protocol version 2025-06-18, stateless, POST only) and is not modelled here because it is a JSON-RPC transport rather than REST; its tools are create_inbox, wait_for_code, list_messages, get_message, delete_inbox, create_account, get_balance, create_deposit, deposit_status and pricing.'
servers:
- url: https://getcourier.dev
tags:
- name: Deposits
  description: Crypto deposits that fund credits.
paths:
  /v1/deposits:
    post:
      tags:
      - Deposits
      summary: Create a crypto deposit
      description: Creates a deposit with a pay_to address, an exact amount unique to this deposit, and a wallet URI. Send exactly `amount` from your own wallet; credits are added when the transfer confirms. GetCourier never holds private keys and never sends funds.
      operationId: createDeposit
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DepositRequest'
      responses:
        '201':
          description: Deposit created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deposit'
        '400':
          description: Rail disabled or amount out of range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or unknown account_key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/deposits/{id}:
    get:
      tags:
      - Deposits
      summary: Read one deposit
      operationId: getDeposit
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The deposit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deposit'
        '401':
          description: Missing or unknown account_key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Deposit not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      - code
      - message
      - retryable
      properties:
        error:
          const: true
        code:
          type: string
          examples:
          - FREE_QUOTA_EXCEEDED
          - INSUFFICIENT_CREDITS
          - PAYMENT_REQUIRED
          - ALIAS_RESERVED
          - RAIL_DISABLED
          - UNAUTHORIZED
          - NOT_OWNER
        message:
          type: string
        retryable:
          type: boolean
        hint:
          type:
          - string
          - 'null'
        retry_after_seconds:
          type: integer
        request_id:
          type: string
        payment:
          $ref: '#/components/schemas/Payment'
          description: Present on HTTP 402 responses.
    DepositRequest:
      type: object
      additionalProperties: false
      required:
      - rail
      - usd
      properties:
        rail:
          type: string
          enum:
          - usdc-base
          - btc
          description: Payment rail. Disabled rails return 400 RAIL_DISABLED.
        usd:
          type: number
          exclusiveMinimum: 0
          description: Deposit size in US dollars. Bounded by the minimum deposit and per-deposit maximum published at GET /v1/pricing.
    Deposit:
      type: object
      required:
      - deposit_id
      - account_id
      - rail
      - pay_to
      - amount
      - amount_atomic
      - credits
      - status
      - created_at
      - expires_at
      - uri
      properties:
        deposit_id:
          type: string
          examples:
          - dep_1a2b3c4d5e6f
        account_id:
          type: string
        rail:
          type: string
          enum:
          - usdc-base
          - btc
        pay_to:
          type: string
          description: Public deposit address (EVM address for usdc-base, Bitcoin address for btc).
        amount:
          type: string
          description: Exact amount to send, as a decimal string (USDC 6 dp, BTC 8 dp). Unique to this deposit.
        amount_atomic:
          type: string
          description: Amount in the asset's smallest unit (USDC micro-units, BTC satoshis).
        credits:
          type: integer
          description: Credits added when the deposit confirms; fixed at creation.
        status:
          type: string
          enum:
          - pending
          - paid
          - expired
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        uri:
          type: string
          description: 'Wallet URI: ethereum:<usdc>@8453/transfer?address=<pay_to>&uint256=<amount_atomic> or bitcoin:<pay_to>?amount=<amount>.'
        paid_at:
          type: string
          format: date-time
        chain_ref:
          type: string
          description: 'Chain reference that credited the deposit: <txHash>:<logIndex> for usdc-base, <txid>:<vout> for btc.'
    Payment:
      type: object
      required:
      - pricing
      - steps
      properties:
        pricing:
          type: string
          examples:
          - https://getcourier.dev/v1/pricing
        steps:
          type: array
          items:
            type: string
          examples:
          - - POST /v1/accounts
            - POST /v1/deposits
            - 'retry with Authorization: Bearer <account_key>'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Either the inbox-scoped read_token returned at inbox creation, or an account_key (cak_...) returned by POST /v1/accounts. Sent as `Authorization: Bearer <token>`; never accepted in the query string.'