openapi: 3.1.0
info:
  title: Crown API & Webhooks Accounts Claims API
  version: 1.0.0
  description: 'Open API 3 docs for Crown API


    Webhook events that Crown will POST to your configured endpoint URL. All webhooks expect a 200 OK response. Payloads use kebab-case for all keys to match the Crown API conventions.'
servers:
- url: https://app.crown-brlv.com
  description: Production server
tags:
- name: Claims
paths:
  /api/v0/claims:
    get:
      responses:
        '200':
          description: Claimable balance retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  available-balance:
                    type: string
                    format: decimal
                    description: Total available balance that can be claimed
                    example: '350.50'
                additionalProperties: false
                required:
                - available-balance
        '400':
          description: Bad request - Invalid input parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type: string
                    additionalProperties: false
                    required:
                    - type
                    - message
                    - code
                    description: Bad request error details
                additionalProperties: false
                required:
                - error
        '403':
          description: Forbidden - Access denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type: string
                    additionalProperties: false
                    required:
                    - type
                    - message
                    - code
                    description: Forbidden access error details
                additionalProperties: false
                required:
                - error
        '404':
          description: Not found - Resource does not exist
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type: string
                    additionalProperties: false
                    required:
                    - type
                    - message
                    - code
                    description: Resource not found error details
                additionalProperties: false
                required:
                - error
        '422':
          description: Unprocessable entity - Validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type: string
                    additionalProperties: false
                    required:
                    - type
                    - message
                    - code
                    description: Validation error details
                additionalProperties: false
                required:
                - error
      summary: Get claimable balance
      description: Returns the total available balance that can be claimed
      tags:
      - Claims
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  oneOf:
                  - type: string
                  - type: number
                    format: double
                  description: Amount to claim from reward certificates
                  example: '100.00'
                target-asset-code:
                  type: string
                  description: 'Destination asset: ''brl'' for bank transfer or ''brlv'' for on-chain tokens'
                  example: brlv
                  enum:
                  - brl
                  - brlv
              additionalProperties: false
              required:
              - amount
      responses:
        '200':
          description: Claim submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  claim:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: Claims request unique identifier
                        example: 550e8400-e29b-41d4-a716-446655440003
                      gross-amount:
                        type: string
                        format: decimal
                        description: Total gross amount of the claims
                        example: '100.00'
                      net-amount:
                        type: string
                        format: decimal
                        description: Net amount after taxes and fees
                        example: '85.00'
                      tax-amount:
                        type: string
                        format: decimal
                        description: Total tax amount deducted
                        example: '15.00'
                      fees:
                        type: string
                        format: decimal
                        description: Processing fees
                        example: '0.00'
                      status:
                        type: string
                        enum:
                        - created
                        - failed
                        - completed
                        - processing
                        - canceled
                        description: Current status of the claims request
                        example: created
                      updated-at:
                        type: string
                        description: Last update timestamp
                        example: '2025-09-30T19:21:57.838913Z'
                    additionalProperties: false
                    required:
                    - id
                    - gross-amount
                    - net-amount
                    - tax-amount
                    - fees
                    - status
                    - updated-at
                    description: Details of the submitted claim request
                additionalProperties: false
                required:
                - claim
        '400':
          description: Bad request - Invalid input parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type: string
                    additionalProperties: false
                    required:
                    - type
                    - message
                    - code
                    description: Bad request error details
                additionalProperties: false
                required:
                - error
        '403':
          description: Forbidden - Access denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type: string
                    additionalProperties: false
                    required:
                    - type
                    - message
                    - code
                    description: Forbidden access error details
                additionalProperties: false
                required:
                - error
        '404':
          description: Not found - Resource does not exist
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type: string
                    additionalProperties: false
                    required:
                    - type
                    - message
                    - code
                    description: Resource not found error details
                additionalProperties: false
                required:
                - error
        '422':
          description: Unprocessable entity - Validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type: string
                    additionalProperties: false
                    required:
                    - type
                    - message
                    - code
                    description: Validation error details
                additionalProperties: false
                required:
                - error
      summary: Submit a claim request
      description: Submits a claim for a specified amount from reward certificates
      tags:
      - Claims
  /api/v0/claims/certificates:
    get:
      responses:
        '200':
          description: Claimable certificates retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  certificates:
                    type: array
                    items:
                      type: object
                      properties:
                        certificate-id:
                          type: string
                          format: uuid
                          description: Reward certificate unique identifier
                          example: 550e8400-e29b-41d4-a716-446655440010
                        status:
                          type: string
                          enum:
                          - accruing
                          - frozen
                          description: Current status of the certificate
                          example: accruing
                        claimable-amount:
                          type: string
                          format: decimal
                          description: Amount currently claimable from this certificate
                          example: '150.25'
                      additionalProperties: false
                      required:
                      - certificate-id
                      - status
                      - claimable-amount
                    description: List of reward certificates with claimable amounts
                  total-claimable:
                    type: string
                    format: decimal
                    description: Total claimable amount across all certificates
                    example: '350.50'
                additionalProperties: false
                required:
                - certificates
                - total-claimable
        '400':
          description: Bad request - Invalid input parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type: string
                    additionalProperties: false
                    required:
                    - type
                    - message
                    - code
                    description: Bad request error details
                additionalProperties: false
                required:
                - error
        '403':
          description: Forbidden - Access denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type: string
                    additionalProperties: false
                    required:
                    - type
                    - message
                    - code
                    description: Forbidden access error details
                additionalProperties: false
                required:
                - error
        '404':
          description: Not found - Resource does not exist
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type: string
                    additionalProperties: false
                    required:
                    - type
                    - message
                    - code
                    description: Resource not found error details
                additionalProperties: false
                required:
                - error
        '422':
          description: Unprocessable entity - Validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type: string
                    additionalProperties: false
                    required:
                    - type
                    - message
                    - code
                    description: Validation error details
                additionalProperties: false
                required:
                - error
      summary: List claimable reward certificates
      description: Returns a list of reward certificates with their claimable amounts
      tags:
      - Claims
components:
  securitySchemes:
    JwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT-based authentication.
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your account API Key
    signature:
      type: apiKey
      in: header
      name: X-Crown-Signature
      description: HMAC-SHA256 signature of the request body using your webhook secret. Verify this signature to ensure the webhook is from Crown.
x-webhook-security:
  note: All webhook requests include an X-Crown-Signature header containing an HMAC-SHA256 signature of the request body. Use your webhook secret (provided when registering the webhook) to verify the signature and ensure the request is authentic.
  algorithm: HMAC-SHA256
  header: X-Crown-Signature
  verification-steps:
  - 1. Extract the X-Crown-Signature header from the request
  - 2. Compute HMAC-SHA256 of the raw request body using your webhook secret
  - 3. Compare the computed signature with the header value
  - 4. Only process the webhook if signatures match
  example-code:
    node-js: "const crypto = require('crypto');\nconst signature = crypto.createHmac('sha256', webhookSecret)\n  .update(JSON.stringify(requestBody))\n  .digest('hex');\nconst isValid = signature === req.headers['x-crown-signature'];"
    python: "import hmac\nimport hashlib\nimport json\n\nsignature = hmac.new(\n    webhook_secret.encode('utf-8'),\n    json.dumps(request_body).encode('utf-8'),\n    hashlib.sha256\n).hexdigest()\nis_valid = signature == request.headers['x-crown-signature']"