BVNK Return API

openapi: 3.2.0
info:
  description: Layer1 API making management of crypto assets simple and easy
  title: Digital Asset Return API
  version: 1.0.0
servers:
- description: Staging
  url: https://api.staging.layer1.com
tags:
- name: Return
paths:
  /digital/v1/returns:
    post:
      description: Create a new blockchain transaction meant to return previously deposited funds
      operationId: createReturnTransactionRequest
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReturnRequest'
        required: true
      responses:
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Request invalid
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Service Unavailable
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Standard error response
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRequest'
          description: Accepted
      security:
      - oauth2:
        - transactions:edit
      - httpSignature: []
      summary: Create return transaction request
      tags:
      - Return
      x-content-type: application/json
      x-accepts:
      - application/json
components:
  schemas:
    Detail:
      example:
        documentLink: documentLink
        errors:
          key:
          - errors
          - errors
      properties:
        documentLink:
          type: string
        errors:
          additionalProperties:
            items:
              type: string
    TransactionRequest:
      example:
        reference: myUniqueRef333
        createdAt: 2000-01-23 04:56:07+00:00
        sources:
        - amount: ''
          address: 103929005307927756724354605802047639613112342136
          tag: 123456789
          asset: ETH
        - amount: ''
          address: 103929005307927756724354605802047639613112342136
          tag: 123456789
          asset: ETH
        requestId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        failure:
          reason: INSUFFICIENT_FUNDS
          message: insufficient funds on address 0x1234567890abcdef1234567890abcdef12345678
        assetPoolId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        destinations:
        - amount: ''
          address: 103929005307927756724354605802047639613112342136
          tag: 123456789
          asset: ETH
        - amount: ''
          address: 103929005307927756724354605802047639613112342136
          tag: 123456789
          asset: ETH
        asset: USDT
        type: DEPOSIT
        network: ETHEREUM
        status: BLOCKED
        updatedAt: 2000-01-23 04:56:07+00:00
      properties:
        requestId:
          description: transaction request id
          format: uuid
          type: string
        asset:
          description: currency
          example: USDT
          type: string
        assetPoolId:
          description: asset pool id
          format: uuid
          type: string
        network:
          description: crypto network
          example: ETHEREUM
          type: string
        reference:
          description: custom identifier supplied for transaction that is used to link transaction to specific customer or use case
          example: myUniqueRef333
          type: string
        status:
          description: transaction request status
          enum:
          - BLOCKED
          - CONFIRMED
          - CREATED
          - DETECTED
          - FAILED
          - FUNDS_RESERVED
          - HELD
          - REJECTED
          - SCREENING_PASSED
          - SCREENING_REQUESTED
          - SIGNED
          - SUCCESS
          - UNCONFIRMED
          - REPLACED
          type: string
        sources:
          description: requested list of addresses and amounts that fund the transaction
          items:
            $ref: '#/components/schemas/Participant'
          type: array
        destinations:
          description: requested list of recipient addresses and amounts that benefit from the transaction
          items:
            $ref: '#/components/schemas/Participant'
          type: array
        type:
          description: transaction request type
          enum:
          - DEPOSIT
          - WITHDRAWAL
          - CONSOLIDATION
          - RETURN
          - STAKE
          - UNSTAKE
          - DELEGATE
          - UNDELEGATE
          - RELEASE
          type: string
        createdAt:
          description: timestamp when transaction request was created
          format: date-time
          type: string
        updatedAt:
          description: timestamp when transaction request was updated
          format: date-time
          type: string
        failure:
          $ref: '#/components/schemas/Failure'
    Participant:
      example:
        amount: ''
        address: 103929005307927756724354605802047639613112342136
        tag: 123456789
        asset: ETH
      properties:
        address:
          description: blockchain address
          example: 103929005307927756724354605802047639613112342136
          type: string
        amount: {}
        asset:
          description: Optional currency if different than in parent object
          example: ETH
          type: string
        tag:
          description: destination tag that serves as optional payment identifier. Only applicable to select networks like Ripple, Solana etc.
          example: 123456789
          type: string
    Failure:
      example:
        reason: INSUFFICIENT_FUNDS
        message: insufficient funds on address 0x1234567890abcdef1234567890abcdef12345678
      properties:
        reason:
          description: reason for failure
          example: INSUFFICIENT_FUNDS
          type: string
        message:
          description: error message
          example: insufficient funds on address 0x1234567890abcdef1234567890abcdef12345678
          type: string
    ReturnRequest:
      example:
        destinationAddress: destinationAddress
        transactionId: transactionId
      properties:
        transactionId:
          description: ID of the transaction to return
          type: string
        destinationAddress:
          description: address into which funds should be returned
          type: string
    ApiError:
      example:
        code: code
        details:
          documentLink: documentLink
          errors:
            key:
            - errors
            - errors
        message: message
        status: status
      properties:
        code:
          type: string
        status:
          type: string
        message:
          type: string
        details:
          $ref: '#/components/schemas/Detail'
  securitySchemes:
    openId:
      openIdConnectUrl: https://auth.sandbox.layer1.com/auth/realms/bvnk/.well-known/openid-configuration
      type: openIdConnect
    httpSignature:
      scheme: signature
      type: http
    oauth2:
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://auth.sandbox.layer1.com/auth/realms/bvnk/protocol/openid-connect/token
      type: oauth2