openapi: 3.0.3
info:
  title: Grassroots Economics
  description: CIC ETH API
  termsOfService: bzz://grassrootseconomics.eth/terms
  contact:
    name: Grassroots Economics
    url: https://www.grassrootseconomics.org
    email: will@grassecon.org
  license:
    name: GPLv3
  version: 0.1.0
servers:
  - url: /
paths:
  /default_token:
    description: Retrieves the default fallback token of the custodial network.
    get:
      tags:
        - Token
      description: Retrieve transactions
      operationId: get_default_token
      responses:
        "200":
          description: OK.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Token"
      x-openapi-router-controller: cic_eth.server.controllers.token_controller
  /balance:
    description: Retrieves the current token balance of the given address
    get:
      tags:
        - Account
      description: Retrieve Address Balance
      operationId: account_balance
      parameters:
        - name: address
          in: query
          required: true
          schema:
            type: string
            example: "0xe88ba386f0efc7117e8d0d17a750fce492516ecb"
        - name: token_symbol
          in: query
          required: true
          schema:
            type: string
        - name: include_pending
          in: query
          required: false
          schema:
            type: boolean
            default: true
      responses:
        "200":
          description: OK.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TokenBalance"

      x-openapi-router-controller: cic_eth.server.controllers.account_controller
  /transactions:
    description:
      Retrieve an aggregate list of latest transactions of internal and
      (optionally) external origin in reverse chronological order.
    get:
      tags:
        - Account
      description: Retrieve Address Balance
      operationId: list_transactions
      parameters:
        - name: address
          in: query
          required: true
          schema:
            type: string
            example: "0xe88ba386f0efc7117e8d0d17a750fce492516ecb"
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 10
      responses:
        "200":
          description: OK.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Transaction"
      x-openapi-router-controller: cic_eth.server.controllers.account_controller
  /create_account:
    description:
      Creates a new blockchain address encrypted with the given password
      and returns the new address
    post:
      tags:
        - Account
      description: Creates  a new blockchain address
      operationId: create_account_post
      parameters:
        - name: password
          in: query
          required: false
          allowReserved: true
          schema:
            type: string
        - name: register
          in: query
          required: false
          allowReserved: true
          schema:
            type: boolean
            default: true
      responses:
        "200":
          description: Address of the new account
          content:
            application/json:
              schema:
                type: string
                example: "bea54d37f1a469515bda96e116695cedd323c182"
      x-openapi-router-controller: cic_eth.server.controllers.account_controller
  /transfer:
    description: Performs a transfer of ERC20 tokens from one address to another.
    post:
      tags:
        - Account
      description: Performs a transfer of ERC20 tokens from one address to another.
      operationId: transfer
      parameters:
        - name: from_address
          in: query
          required: true
          schema:
            type: string
            example: "0xbea54d37f1a469515bda96e116695cedd323c182"
        - name: to_address
          in: query
          required: true
          schema:
            type: string
            example: "0x8264d4c224d0c74c98295bfab2f216c2d7b18c8c"
        - name: value
          in: query
          required: true
          schema:
            type: integer
        - name: token_symbol
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Transaction hash for transfer operation
          content:
            application/json:
              schema:
                type: string
      x-openapi-router-controller: cic_eth.server.controllers.account_controller
  /transfer_from:
    post:
      tags:
        - Account
      description:
        Performs a transfer of ERC20 tokens by one address on behalf of
        another address to a third party.
      operationId: transfer_from
      parameters:
        - name: from_address
          in: query
          description: Ethereum address of sender
          required: true
          schema:
            type: string
        - name: to_address
          in: query
          description: Ethereum address of recipient
          required: true
          schema:
            type: string
        - name: value
          in: query
          description: Estimated return from conversion
          required: true
          schema:
            type: integer
        - name: token_symbol
          in: query
          description: ERC20 token symbol of token to send
          required: true
          schema:
            type: string
        - name: spender_address
          in: query
          description: Ethereum address of recipient
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Transaction hash for transfer operation
          content:
            application/json:
              schema:
                type: string
      x-openapi-router-controller: cic_eth.server.controllers.account_controller
components:
  schemas:
    Transaction:
      type: object
      properties:
        block_number:
          type: integer
          format: int32
          example: 24531
        date_checked:
          type: string
          example: 2021-11-12T09:36:40.725296
        date_created:
          type: string
          example: 2021-11-12T09:36:40.131292
        date_updated:
          type: string
          example: 2021-11-12T09:36:40.131292
        destination_token:
          type: string
          example: 0x3ff776b6f888980def9d4220858803f9dc5e341e
        destination_token_decimals:
          type: integer
          format: int32
          example: 6
        destination_token_symbol:
          type: string
          example: COFE
        from_value:
          type: integer
          format: int32
          example: 100000000
        hash:
          type: string
          example: 0xc7d160b4f1c89f09cbccbc2c4f6a72760bc3c1634a88438870c31b2e4d9e2bf3
        nonce:
          type: integer
          format: int32
          example: 1
        recipient:
          type: string
          example: 872e1ec9d499b242ebfcfd0a279a4c3e0cd472c0
        sender:
          type: string
          example: 1a92b05e0b880127a4c26ac0f68a52df3ac6b89d
        signed_tx:
          type: string
          example: 0xf8aa018310c8e0837a1200943ff776b6f888980def9d4220858803f9dc5e341e80b844a9059cbb000000000000000000000000872e1ec9d499b242ebfcfd0a279a4c3e0cd472c00000000000000000000000000000000000000000000000000000000005f5e10082466ca0617d50ea726dfe61d6dc5e8a4a85cf7469514f394250cecb019006317cfb94d3a04930e14524f0a87db623a80e0f841ab613f693f5031c6a136873052ae7bba08e
        source_token:
          type: string
          example: 0x3ff776b6f888980def9d4220858803f9dc5e341e
        source_token_decimals:
          type: integer
          format: int32
          example: 6
        source_token_symbol:
          type: string
          example: COFE
        status:
          type: string
          example: SUCCESS
        status_code:
          type: integer
          format: int32
          example: 4104
        timestamp:
          type: integer
          format: int32
          example: 1636709800
        to_value:
          type: integer
          format: int32
          example: 100000000
        tx_hash:
          type: string
          example: 0xc7d160b4f1c89f09cbccbc2c4f6a72760bc3c1634a88438870c31b2e4d9e2bf3
        tx_index:
          type: integer
          format: int32
          example: 0

    Token:
      type: object
      properties:
        symbol:
          type: string
          description: Token Symbol
        address:
          type: string
          description: Token Address
        name:
          type: string
          description: Token Name
        decimals:
          type: integer
          description: Decimals
      example:
        symbol: "GTF"
        address: "3FF776B6f888980DEf9d4220858803f9dC5e341e"
        decimals: 6
        name: "Gift Token"
    TokenBalance:
      type: object
      properties:
        address:
          type: string
        converters:
          type: array
          items:
            type: string
        balance_network:
          type: integer
        balance_incoming:
          type: integer
        balance_outgoing:
          type: integer
        balance_available:
          type: integer
      example:
        balance_network: 0
        address: address
        balance_incoming: 6
        balance_available: 5
        converters:
          - converters
          - converters
        balance_outgoing: 1