BanQu

BanQu Smart Contracts API

Automation workflows that react to system events

GitHub OpenAPI

Documentation

📖
Documentation
https://api.banqu.app/openapi
📖
APIReference
https://api.banqu.app/openapi
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/banqu/refs/heads/main/authentication/banqu-authentication.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/banqu/refs/heads/main/openapi/banqu-smart-contracts-api-openapi.yml

Other Resources

🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/banqu/refs/heads/main/conventions/banqu-conventions.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/banqu/refs/heads/main/errors/banqu-problem-types.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/banqu/refs/heads/main/data-model/banqu-data-model.yml
🔗
Webhooks
https://raw.githubusercontent.com/api-evangelist/banqu/refs/heads/main/asyncapi/banqu-webhooks.yml

OpenAPI Specification

banqu-smart-contracts-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: BanQu Smart Contracts API
  version: 3.3.4
  description: The BanQu API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP verbs, which can be understood by off-the-shelf HTTP clients, and [JSON](http://www.json.org) for input and output.
servers:
- url: https://banqu.app:443/api/v1
security:
- Bearer: []
tags:
- name: Smart Contracts
  description: Automation workflows that react to system events
paths:
  /smart-contracts:
    get:
      description: List smart contracts
      tags:
      - Smart Contracts
      responses:
        '200':
          description: list of account's smart contracts
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                  - $ref: '#/components/schemas/SmartContract'
                  - type: object
                    properties:
                      description:
                        type: string
                  - $ref: '#/components/schemas/ScimResourceMetadata'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
    post:
      description: Create smart contract
      tags:
      - Smart Contracts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmartContract'
      responses:
        '201':
          $ref: '#/components/responses/201'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
  /smart-contracts/{contractId}:
    parameters:
    - name: contractId
      description: Smart contract identifier
      in: path
      schema:
        type: string
      required: true
    get:
      description: Get smart contract details
      tags:
      - Smart Contracts
      responses:
        '200':
          description: Smart contract details
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SmartContract'
                - $ref: '#/components/schemas/ScimResourceMetadata'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
    put:
      description: Update smart contract
      tags:
      - Smart Contracts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmartContract'
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '422':
          $ref: '#/components/responses/422'
    delete:
      description: Deactivate smart contract
      tags:
      - Smart Contracts
      responses:
        '204':
          $ref: '#/components/responses/204'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '422':
          $ref: '#/components/responses/422'
  /smart-contracts/{contractId}/history:
    parameters:
    - name: contractId
      description: Smart contract identifier
      in: path
      schema:
        type: string
      required: true
    get:
      description: Get smart contract execution history
      tags:
      - Smart Contracts
      responses:
        '200':
          description: Smart contract execution history
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    state:
                      type: string
                      enum:
                      - running
                      - canceled
                      - complete
                      - failed
                    steps:
                      type: array
                      items:
                        type: object
                        properties:
                          at:
                            $ref: '#/components/schemas/Timestamp'
                          type:
                            type: string
                            enum:
                            - running
                            - canceled
                            - complete
                            - failed
                          message:
                            type: string
                        additionalProperties: false
                        required:
                        - at
                        - type
                  additionalProperties: false
                  required:
                  - id
                  - state
                  - steps
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /smart-contracts/{contractId}/restore:
    parameters:
    - name: contractId
      description: Smart contract identifier
      in: path
      schema:
        type: string
      required: true
    post:
      description: Reactivate smart contract
      tags:
      - Smart Contracts
      responses:
        '204':
          $ref: '#/components/responses/204'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '422':
          $ref: '#/components/responses/422'
  /smart-contracts/triggers:
    get:
      description: Get available triggers
      tags:
      - Smart Contracts
      responses:
        '200':
          description: List of available triggers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SmartContractTrigger'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
  /smart-contracts/triggers/{triggerId}:
    parameters:
    - name: triggerId
      description: Trigger identifier
      in: path
      schema:
        type: string
      required: true
    get:
      description: Get trigger details
      tags:
      - Smart Contracts
      responses:
        '200':
          description: Trigger details
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SmartContractTrigger'
                - type: object
                  properties:
                    schema:
                      $ref: '#/components/schemas/JsonSchema'
                    sample:
                      type: object
                      additionalProperties: true
                    authenticationRequired:
                      description: Indicates if the trigger is being invoked in a different account context and a smart contract authentication token is required
                      type: boolean
                  additionalProperties: false
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
  /smart-contracts/actions:
    get:
      description: List available actions
      tags:
      - Smart Contracts
      parameters:
      - name: type
        description: Optional Action type filter
        in: query
        schema:
          type: string
          enum:
          - read
          - write
      responses:
        '200':
          description: List of actions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmartContractAction'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
  /smart-contracts/actions/{actionId}:
    parameters:
    - name: actionId
      description: Smart contract action identifier
      in: path
      schema:
        type: string
      required: true
    get:
      description: Get smart contract action details
      tags:
      - Smart Contracts
      responses:
        '200':
          description: Smart contract action details
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SmartContractAction'
                - type: object
                  properties:
                    schema:
                      $ref: '#/components/schemas/JsonSchema'
                    sample:
                      type: object
                      additionalProperties: true
                    mappingTemplate:
                      $ref: '#/components/schemas/Mapping'
                  additionalProperties: false
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
components:
  responses:
    '404':
      description: "HTTP 404 - Not Found \nRequested resource could not be found"
    '201':
      description: HTTP 201 - Created
      headers:
        Location:
          schema:
            type: string
          description: Url of the created entity
    '401':
      description: "HTTP 401 - Unauthorized \nUser is not authenticated or session has expired"
    '204':
      description: "HTTP 204 - No Content \nThe request has been processed, but no content will be provided in response"
    '422':
      description: "HTTP 422 - Unprocessable Request \nThe server understands the content type of the request entity and the syntax of the request is correct, but was unable to process the contained instructions"
    '400':
      description: "HTTP 400 - Bad Request \nThe request is formatted incorrectly, most likely some of the required parameters are missed"
    '403':
      description: "HTTP 403 - Forbidden \nNot authorized to access selected resource"
  schemas:
    WorkflowStepName:
      type:
      - string
      - 'null'
      description: Optional unique alpha-numeric name of the step. Data produced during the step execution can be referred by this name
      pattern: ^[a-zA-Z_$][\da-zA-Z_]*$
    JsonSchema:
      title: JSON Schema
      description: https://json-schema.org/draft-07/schema#
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        type:
          type: string
          enum:
          - array
          - boolean
          - integer
          - 'null'
          - number
          - object
          - string
          example: object
        required:
          type: array
          items:
            type: string
          uniqueItems: true
        additionalProperties:
          oneOf:
          - type: boolean
          - type: object
        properties:
          type: object
      example:
        type: object
        properties:
          field1:
            type: string
        required:
        - field1
        additionalProperties: false
    SmartContractAction:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        title:
          type: string
        groups:
          type: array
          items:
            type: string
          uniqueItems: true
        description:
          type: string
      required:
      - title
      - groups
    ScimResourceMetadata:
      type: object
      readOnly: true
      properties:
        displayName:
          type: string
          readOnly: true
        meta:
          type: object
          properties:
            resourceType:
              type: string
              readOnly: true
            created:
              type: number
              readOnly: true
            lastModified:
              type: number
              readOnly: true
          required:
          - resourceType
          - created
          - lastModified
      required:
      - displayName
      - meta
    WorkflowSteps:
      title: Workflow Steps
      type: array
      items:
        oneOf:
        - $ref: '#/components/schemas/WorkflowMapping'
        - $ref: '#/components/schemas/WorkflowFilter'
        - $ref: '#/components/schemas/WorkflowUniquenessFilter'
        - $ref: '#/components/schemas/WorkflowAction'
        - $ref: '#/components/schemas/WorkflowRequest'
      example:
      - type: filter
        condition: selectedAssetId !== '' && receiverId !== ''
      - type: map
        mapping:
          map:
            assetId: selectedAssetId
            body:
              map:
                receiverId: receiverId
                qty: '1'
                destinationId: 'null'
                price: '0'
                priceCurrency: '''USD'''
      - type: action
        action: eyJwYXRoIjoiL2Fzc2V0cy97YXNzZXRJZH0vdHJhbnNmZXJzIiwibWV0aG9kIjoicG9zdCJ9
    WorkflowFilter:
      title: Workflow Filter
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowStepName'
        input:
          $ref: '#/components/schemas/WorkflowStepInput'
        type:
          type: string
          enum:
          - filter
        condition:
          type: string
          description: JS expression in a 'filter' step that returns `true` or `false` to indicate if execution should proceed
      required:
      - type
      - condition
    WorkflowRequest:
      title: Workflow Request
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowStepName'
        input:
          $ref: '#/components/schemas/WorkflowStepInput'
        type:
          type: string
          enum:
          - request
        method:
          type: string
          enum:
          - get
          - list
          - post
          - put
          - patch
          - delete
          - head
          - options
        url:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
      required:
      - type
      - method
      - url
    Mapping:
      type: object
      properties:
        from:
          type: string
          description: Context source to map data from
        forEach:
          type: string
          description: Array context source to map data from
        map:
          type: object
          description: Object fields mapping
      additionalProperties: true
      example:
        map:
          outputField: inputField
    SmartContract:
      type: object
      additionalProperties: false
      properties:
        title:
          type: string
          description: Smart contract title
        authToken:
          type: string
          description: Optional auth token to use for smart contract authentication. Write-only property
        authTokenSig:
          type: string
          description: Signature of the stored auth token for its presence and uniqueness validation
          readOnly: true
        workflow:
          type: object
          additionalProperties: false
          properties:
            triggerId:
              type: string
            steps:
              $ref: '#/components/schemas/WorkflowSteps'
          required:
          - triggerId
          - steps
        ownerId:
          type: string
          readOnly: true
      required:
      - title
      - workflow
    SmartContractTrigger:
      type: object
      properties:
        id:
          type: string
          description: Unique trigger identifier
          readOnly: true
        title:
          type: string
          description: Custom title
    WorkflowAction:
      title: Workflow Action
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowStepName'
        input:
          $ref: '#/components/schemas/WorkflowStepInput'
        type:
          type: string
          enum:
          - action
        action:
          type: string
          description: ID of the Open API endpoint to execute. Base64 encoded JSON object containing endpint properties `{ method, path }`
      required:
      - type
      - action
    WorkflowStepInput:
      type:
      - string
      - 'null'
      description: Name of one of the previous steps that should be used as a primary input. By default the latest step name is used
      pattern: ^[a-zA-Z_$][\da-zA-Z_]*$
    WorkflowUniquenessFilter:
      title: Workflow Uniqueness Filter
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowStepName'
        input:
          $ref: '#/components/schemas/WorkflowStepInput'
        type:
          type: string
          enum:
          - unique
        criteria:
          type: string
          description: JS expression in a 'unique' step that returns a key used to identify object uniquenss
      required:
      - type
      - criteria
    Timestamp:
      type: number
      description: Number of milliseconds elapsed since January 1, 1970 00:00:00 UTC
      example: 1568894551000
    WorkflowMapping:
      title: Workflow Mapping
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowStepName'
        input:
          $ref: '#/components/schemas/WorkflowStepInput'
        type:
          type: string
          enum:
          - map
        mapping:
          $ref: '#/components/schemas/Mapping'
      required:
      - type
      - mapping
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Your authentication token