openapi: 3.1.0
info:
  title: Crown API & Webhooks Accounts Transfers 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: Transfers
paths:
  /api/v0/transfers:
    get:
      parameters:
      - in: query
        name: source-address
        required: false
        schema:
          type: string
          example: '0xabcdef1234567890abcdef1234567890abcdef12'
        description: Filter by source wallet address
      - in: query
        name: target-address
        required: false
        schema:
          type: string
          example: '0x1234567890abcdef1234567890abcdef12345678'
        description: Filter by target wallet address
      - in: query
        name: asset
        required: false
        schema:
          type: string
          enum:
          - tempo/brlv
          - eth-base/brlv
          - eth-mainnet/brlv
          - fiat/brl
          - eth-base/usdt
          - fiat/usd
          - eth-mainnet/usdt
          - eth-mainnet/usdc
          - eth-base/wbrly
          - eth-base/usdc
          - eth-base/brly
          example: eth-base/brlv
        description: Filter by asset
      - in: query
        name: state
        required: false
        schema:
          type: string
          enum:
          - created
          - failed
          - completed
          - pending
          example: completed
        description: Filter by transfer state
      responses:
        '200':
          description: Transfers list retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  transfers:
                    type: array
                    items:
                      type: object
                      properties:
                        amount:
                          type: string
                          format: decimal
                          description: Amount being transferred
                          example: '100.50'
                        state-updated-at:
                          type: string
                          example: '2024-01-15T10:30:00Z'
                          format: date-time
                          description: ISO 8601 timestamp when the transfer state was last updated
                        tx-hash:
                          oneOf:
                          - type: string
                          - type: 'null'
                          description: Blockchain transaction hash once available
                          example: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
                        state:
                          type: string
                          enum:
                          - created
                          - failed
                          - completed
                          - pending
                          description: Current state of the transfer
                          example: created
                        source-address:
                          type: string
                          description: Source wallet address
                          example: '0xabcdef1234567890abcdef1234567890abcdef12'
                        id:
                          type: string
                          format: uuid
                          description: Unique identifier for the transfer
                          example: 660e8400-e29b-41d4-a716-446655440003
                        target-address:
                          type: string
                          description: Target wallet address
                          example: '0x1234567890abcdef1234567890abcdef12345678'
                        created-at:
                          type: string
                          example: '2024-01-15T10:30:00Z'
                          format: date-time
                          description: ISO 8601 timestamp when the transfer was created
                        asset:
                          type: string
                          enum:
                          - tempo/brlv
                          - eth-base/brlv
                          - eth-mainnet/brlv
                          - fiat/brl
                          - eth-base/usdt
                          - fiat/usd
                          - eth-mainnet/usdt
                          - eth-mainnet/usdc
                          - eth-base/wbrly
                          - eth-base/usdc
                          - eth-base/brly
                          description: Asset being transferred
                          example: eth-base/brlv
                      additionalProperties: false
                      required:
                      - amount
                      - state-updated-at
                      - tx-hash
                      - state
                      - source-address
                      - id
                      - target-address
                      - created-at
                      - asset
                    description: List of transfers
                additionalProperties: false
                required:
                - transfers
        '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 transfers
      description: Retrieves a list of token transfers for the authenticated user. Can be filtered by source-address, target-address, asset, or state.
      tags:
      - Transfers
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                source-address:
                  type: string
                  description: Source wallet address (0x...)
                  example: '0xabcdef1234567890abcdef1234567890abcdef12'
                asset:
                  type: string
                  enum:
                  - tempo/brlv
                  - eth-base/brlv
                  - eth-mainnet/brlv
                  - fiat/brl
                  - eth-base/usdt
                  - fiat/usd
                  - eth-mainnet/usdt
                  - eth-mainnet/usdc
                  - eth-base/wbrly
                  - eth-base/usdc
                  - eth-base/brly
                  description: 'Asset to transfer (only token assets supported: eth-base/brlv, eth-base/wbrly)'
                  example: eth-base/brlv
                amount:
                  oneOf:
                  - type: string
                  - type: number
                    format: double
                  description: Amount of tokens to transfer
                  example: '100.50'
                target-address:
                  type: string
                  description: Target wallet address (0x...)
                  example: '0x1234567890abcdef1234567890abcdef12345678'
              additionalProperties: false
              required:
              - source-address
              - asset
              - amount
              - target-address
      responses:
        '200':
          description: Transfer created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  transfer:
                    type: object
                    properties:
                      amount:
                        type: string
                        format: decimal
                        description: Amount being transferred
                        example: '100.50'
                      state-updated-at:
                        type: string
                        example: '2024-01-15T10:30:00Z'
                        format: date-time
                        description: ISO 8601 timestamp when the transfer state was last updated
                      tx-hash:
                        oneOf:
                        - type: string
                        - type: 'null'
                        description: Blockchain transaction hash once available
                        example: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
                      state:
                        type: string
                        enum:
                        - created
                        - failed
                        - completed
                        - pending
                        description: Current state of the transfer
                        example: created
                      source-address:
                        type: string
                        description: Source wallet address
                        example: '0xabcdef1234567890abcdef1234567890abcdef12'
                      id:
                        type: string
                        format: uuid
                        description: Unique identifier for the transfer
                        example: 660e8400-e29b-41d4-a716-446655440003
                      target-address:
                        type: string
                        description: Target wallet address
                        example: '0x1234567890abcdef1234567890abcdef12345678'
                      created-at:
                        type: string
                        example: '2024-01-15T10:30:00Z'
                        format: date-time
                        description: ISO 8601 timestamp when the transfer was created
                      asset:
                        type: string
                        enum:
                        - tempo/brlv
                        - eth-base/brlv
                        - eth-mainnet/brlv
                        - fiat/brl
                        - eth-base/usdt
                        - fiat/usd
                        - eth-mainnet/usdt
                        - eth-mainnet/usdc
                        - eth-base/wbrly
                        - eth-base/usdc
                        - eth-base/brly
                        description: Asset being transferred
                        example: eth-base/brlv
                    additionalProperties: false
                    required:
                    - amount
                    - state-updated-at
                    - tx-hash
                    - state
                    - source-address
                    - id
                    - target-address
                    - created-at
                    - asset
                    description: Details of the created transfer
                additionalProperties: false
                required:
                - transfer
        '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: Transfer tokens between wallets
      description: Transfer tokens from a source wallet to a target wallet. Both source and target should be EVM wallet addresses (0x...).
      tags:
      - Transfers
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']"