crypto_portfolio/README.md

# CryptoPortfolio

pequena aplicação para ir acompanhando a evolução de um portfolio de activos de criptomoedas

"historico_preco.csv"   -> ficheiro CSV com dados historicos diarizados de um activo.

~~~pseudo
data,moeda,simbolo,preco_abertura,preco_maximo,preco_minimo,preco_fecho

<data>              -   data a que se referem os dados. formato: dd-mm-aaaa
<moeda>             -   nome do activo (ex: bitcoin)
<simbolo>           -   simbolo do activo (ex: btc)
<preco_abertura>    -   preco de abertura do activo para esse dia (em EUR)
<preco_maximo>      -   preco máximo atingido pelo activo nesse dia (em EUR)
<preco_minimo>      -   preco minimo atingido pelo activo nesse dia (em EUR)
<preco_fecho>       -   preco de fecho do activo nesse dia (em EUR)
~~~

"portfolio.csv"         -   ficheiro CSV com informação sobre os movimentos de um activo.

~~~pseudo
data,moeda,tipo_movimento,quantidade,preco_movimento

<data>              -   data a que se refere o movimento
<moeda>             -   activo a que se refere o movimento
<tipo_movimento>    -   tipo do movimento ("compra", "venda")
<quantidade>        -   quantidade do activo a que se refere o movimento
<preco_movimento>   -   preco a que foi efectuado o movimento (preco activo * quantidade comprada)
~~~

exemplo:
02-03-2024,bitcoin,compra,0.05,2978.024

este exemplo indica-nos que no dia 02-03-2024 foi comprado 0.05BTC com um custo total de 2978.024EUR

de notar que o preco do movimento é o valor pago por 0.05BTC, não o preco de mercado de 1un de BTC nesta data.

podemos calcular qual o preco de compra por unidade de BTC deste movimento simplesmente:

~~~pseudo
<preco_movimento> / <quantidade> = 59560.48EUR
~~~

consultando na coingecko o preco de mercado de bitcoin à data de 02-03-2024 (cerca de 57560.483EUR), vemos que foi pago um premium de:
    ( ( 59560.48 / 57560.483 ) - 1 ) * 100 = 3.47%

<details>
  <summary>Documentação API</summary>

<https://docs.coingecko.com/v3.0.1/reference/introduction>

API_KEY = "CG-K5RS5VXsdFDip2UvY3z8VjQP"

</details>

## Sidequest - criação de wrapper para a API Coingecko

sim sim, já existe uma (muito bem feita, por sinal!) que pode ser descarregada [aqui](<https://github.com/khooihzhz/coingecko-python>).

esta é a minha tentativa! :D

### Padrões a adoptar

#### Nomes de funções e parâmetros das chamadas API

usar como nome das funções e dos parâmetros os mesmos nomes usados pela API da CoinGecko,por exemplo:

~~~pseudo
documentação:
    'Coin OHLC Chart by ID'
endpoint: 
    https://api.coingecko.com/api/v3/coins/{id}/ohlc
parametros:
    de caminho:
      id (obrigatorio)
    de consulta:    
      vs_currencies (obrigatorio)
      days (obrigatorio)
      precision

função:
    coin_ohlc_chart_by_id()
parametros:
    id
    vs_currencies
    days
    precision
~~~

*Nota: na situação em que o nome do parâmetro for um termo reservado, renomear com nome apropriado e comentar essa alteração*

#### Parâmetros obrigatórios e vazios

nas chamadas de API com parametros obrigatorios, a função deve gerar erro quando o parametro não for passado como argumento ou o tipo de objecto for diferente do esperado

quando houver parametros 'vazios' passados como argumentos, estes não devem ser incluidos no URL de consulta. ( implementado na função API() )

#### Dados devolvidos por chamadas API
  
  **url**     - url completo do endpoint

  **codigo**  - codigo de erro devolvido pelo modulo requests

  **dados**   - dados devolvidos pela chamada, em formato dict[Any, Any]

<details>
  <summary>Documentação Public API</summary>

### endpoints Public API Demo [V3.0.1](https://docs.coingecko.com/v3.0.1/reference/introduction)

✅ - implementado

❌ - não implementado

📖 - documentado

* **ping**

  * ✅ check api server status

* **simple**
  * ✅ coin price by ids

  * ✅ coin price by token addresses

  * ✅ supported currencies list
* **coins**
  * ✅ coins list (id map)

  * ✅ coins list with market data

  * ✅ coin data by id

  * ✅ coin tickers by id

  * ✅ coin historical data by id

  * ✅ coin historical chart data by id

  * ✅ coin historical chart data within time range by id

  * ✅ coin ohlc chart by id
* **contract**
  * ✅ coin data by token address

  * ✅ coin historical chart data by token address

  * ✅ coin historical chart data within time range by token address
* **asset platforms**
  * ✅ assets platforms list (id map)

* **categories**
  * ✅ coins categories list (id map)

  * ✅ coins categories list with market data

* **exchanges**
  * ✅ exchanges list with data

  * ✅ exchanges list (id map)

  * ✅ exchange data by id

  * ✅ exchange tickers by id

  * ✅ exchange volume chart by id
* **derivatives**
  * ✅ derivatives tickers list

  * ✅ derivatives exchange list with data

  * ✅ derivatives exchange data by id

  * ✅ derivatives exchanges list (id map)

* **NFTs (beta)**
  * ✅ nfts list (id map)

  * ✅ nfts collection data by id

  * ✅ nfts collection data by contract address

* **exchange rates**
  * ✅ btc-to-currency exchange rates

* **search**
  * ✅ search queries

* **trending**
  * ✅ trending search list

* **global**
  * ✅ crypto global market data

  * ✅ global de-fi market data

* **companies (beta)**
  * ✅ public companies holdings
</details>

<details>
<summary>Documentação Pro API</summary>

### endpoints Pro API [V3.1.1](https://docs.coingecko.com/reference/introduction)

✅ - implementado

❌ - não implementado

📖 - documentado

* **key**

  * ❌ API usage

* **coins**
  * ❌ top gainers & losers

  * ❌ recently added coins

  * ❌ coin ohcl chart within time range by id (enterprise only)

  * ❌ circulating supply chart by id (enterprise only)

  * ❌ total supply chart by id (enterprise only)

  * ❌ total supply chart within time range by id (enterprise only)

* **asset platforms**
  * ❌ token lists by asset platform id (enterprise only)

* **exchanges**
  * ❌ exchange volume chart within time range by id (enterprise only)

* **NFTs (beta)**
  * ❌ nfts list with market data 

  * ❌ nfts collection historical chart data by id

  * ❌ nfts collection tickers by id

* **global**

  * ❌ global market cap chart data
</details>