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:
  /tokens:
    get:
      tags:
        - Token
      description: Perform a token data lookup from the token index. The token index will enforce unique associations between token symbol and contract address.
      operationId: get_tokens
      parameters:
        - name: token_symbols
          in: query
          description: Token symbol to look up
          required: true
          schema:
            type: array
            example: ["GTF"]
            items:
              type: string
        - name: proof
          in: query
          description: |
            Proofs to add to signature verification for the token
            - None (Default), in which case proof checks are skipped (although there may still be builtin proof checks being performed)
            - Single string, where the same proof is used for each token lookup
            - Array of strings, where the respective proof is used for the respective token. number of proofs must match the number of tokens.
            - Array of lists, where the respective proofs in each list is used for the respective token. number of lists of proofs must match the number of tokens.

          required: false
          schema:
            oneOf:
              - type: array
                items:
                  type: string
              - type: string

      responses:
        "200":
          description: OK.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Token"
  /token:
    get:
      tags:
        - Token
      description: Single-token alias for tokens method.
      operationId: get_token
      parameters:
        - name: token_symbol
          in: query
          description: Token symbol to look up
          required: true
          schema:
            type: string
            example: "GFT"
        - name: proof
          in: query
          description: Proofs to add to signature verification for the token
          required: false
          schema:
            type: string

      responses:
        "200":
          description: OK.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Token"
  /refill_gas:
    post:
      tags:
        - Account
      description: Creates a new gas refill transaction with the registered gas provider address.
      operationId: post_refill_gas
      parameters:
        - name: address
          in: query
          required: true
          schema:
            type: string
            example: "0xe88ba386f0efc7117e8d0d17a750fce492516ecb"
      responses:
        "200":
          description: OK.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Token"
  /default_token:
    get:
      tags:
        - Token
      description: Retrieves the default fallback token of the custodial network.
      operationId: get_default_token
      responses:
        "200":
          description: OK.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Token"
  /balance:
    get:
      tags:
        - Account
      description: Retrieves the current token balance of the given address
      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"

  /transactions:
    get:
      tags:
        - Account
      description: Retrieve an aggregate list of latest transactions of internal and (optionally) external origin in reverse chronological order.
      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"
  /create_account:
    post:
      tags:
        - Account
      description: Creates a new blockchain address encrypted with the given password and returns the new 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"
  /transfer:
    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
  /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
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