AwesomeAPI Forex 💱

Biblioteca JavaScript/TypeScript para conversão de moedas usando a AwesomeAPI brasileira - 100% Gratuita e sem necessidade de API key!


🌟 Destaques

- ✅ 100% Gratuita - Sem necessidade de chave de API
- 🇧🇷 API Brasileira - AwesomeAPI (economia.awesomeapi.com.br)
- ✨ TypeScript - Totalmente tipado
- 🌐 ESM & CommonJS - Suporte para ambos
- 🔄 Tempo Real - Cotações atualizadas
- 💰 Múltiplas Moedas - USD, EUR, BTC, BRL e mais
- 🧪 Testado - Cobertura completa
- 📦 Leve - Apenas axios como dependência
- 🚀 Fácil - API simples e intuitiva

📦 Instalação

``bash
npm install awesomeapi-forex
`

ou

`bash
yarn add awesomeapi-forex
`

🔧 Uso Básico

$3

`typescript
import { ForexClient } from 'awesomeapi-forex';

// Sem necessidade de API key!
const client = new ForexClient();

// Obter taxa de câmbio
const rate = await client.getLatestRate('USD', 'BRL');
console.log(1 USD = ${rate} BRL);

// Converter valores
const converted = await client.convert(100, 'USD', 'BRL');
console.log(100 USD = ${converted} BRL);
`

$3

`javascript
const { ForexClient } = require('awesomeapi-forex');

const client = new ForexClient();

// Uso igual ao exemplo acima
`

📚 Exemplos

$3

`typescript
import { ForexClient } from 'awesomeapi-forex';

const client = new ForexClient();

(async () => {
// USD -> BRL
const rate = await client.getLatestRate('USD', 'BRL');
console.log(1 USD = ${rate} BRL);

// Converter 100 USD para BRL
const converted = await client.convert(100, 'USD', 'BRL');
console.log(100 USD = ${converted} BRL);

// Informações detalhadas
const info = await client.getExchangeRateInfo('EUR', 'BRL');
console.log(info);
// { base: 'EUR', target: 'BRL', rate: 5.71, timestamp: 1696531200000 }
})();
`

$3

`typescript
const client = new ForexClient();

// Bitcoin para Real
const btcBrl = await client.convert(1, 'BTC', 'BRL');
console.log(1 BTC = ${btcBrl} BRL);

// Bitcoin para Dólar
const btcUsd = await client.convert(1, 'BTC', 'USD');
console.log(1 BTC = ${btcUsd} USD);
`

$3

`typescript
const client = new ForexClient();

const amounts = [50, 100, 500, 1000];

for (const amount of amounts) {
const brl = await client.convert(amount, 'USD', 'BRL');
console.log(${amount} USD = ${brl} BRL);
}
`

📖 API

$3

#### Construtor

`typescript
new ForexClient(options?: ForexClientOptions)
`

Opções:
- baseUrl (string, opcional) - URL base customizada da API

Exemplo:
`typescript
const client = new ForexClient();
// ou com URL customizada
const customClient = new ForexClient({
baseUrl: 'https://custom-api.com'
});
`

#### Métodos

##### getLatestRate(baseCurrency, targetCurrency)

Obtém a taxa de câmbio mais recente entre duas moedas.

`typescript
const rate = await client.getLatestRate('USD', 'BRL');
// Retorna: 5.25 (exemplo)
`

Parâmetros:
- baseCurrency (string) - Código da moeda base (ex: 'USD', 'EUR', 'BTC')
- targetCurrency (string) - Código da moeda alvo (ex: 'BRL', 'USD')

Retorna: Promise - Taxa de câmbio

##### convert(amount, from, to)

Converte um valor de uma moeda para outra.

`typescript
const converted = await client.convert(100, 'USD', 'BRL');
// Retorna: 525.00 (exemplo)
`

Parâmetros:
- amount (number) - Valor a ser convertido
- from (string) - Código da moeda de origem
- to (string) - Código da moeda de destino

Retorna: Promise - Valor convertido (arredondado para 2 casas decimais)

##### getExchangeRateInfo(baseCurrency, targetCurrency)

Obtém informações detalhadas sobre a taxa de câmbio.

`typescript
const info = await client.getExchangeRateInfo('EUR', 'BRL');
/* Retorna:
{
base: 'EUR',
target: 'BRL',
rate: 5.71,
timestamp: 1696531200000
}
*/
`

Parâmetros:
- baseCurrency (string) - Código da moeda base
- targetCurrency (string) - Código da moeda alvo

Retorna: Promise

🌍 Moedas Suportadas

A biblioteca suporta todas as moedas disponíveis na AwesomeAPI, incluindo:

$3

- 🇺🇸 USD - Dólar Americano
- 🇧🇷 BRL - Real Brasileiro
- 🇪🇺 EUR - Euro
- 🇬🇧 GBP - Libra Esterlina
- 🇯🇵 JPY - Iene Japonês
- 🇨🇭 CHF - Franco Suíço
- 🇨🇦 CAD - Dólar Canadense
- 🇦🇺 AUD - Dólar Australiano
- E muitas outras...

$3

- ₿ BTC - Bitcoin
- Ξ ETH - Ethereum
- E outras suportadas pela API

Para ver a lista completa, visite: AwesomeAPI Docs

🧪 Testes

`bash


Executar testes

npm test

Testes em modo watch

npm run test:watch

Gerar relatório de cobertura

npm run test:coverage
`

🛠️ Desenvolvimento

`bash


Instalar dependências

npm install

Compilar TypeScript

npm run build

Executar exemplo

npm run example
`

🔒 Tratamento de Erros

`typescript
import { ForexClient } from 'awesomeapi-forex';

const client = new ForexClient();

try {
const rate = await client.getLatestRate('USD', 'BRL');
console.log(rate);
} catch (error) {
console.error('Erro ao obter taxa:', error.message);
}
``

Erros comuns:
- Par de moedas inválido
- Erro de conexão com a API
- Timeout de requisição

📊 Sobre a AwesomeAPI

A AwesomeAPI é uma API brasileira gratuita que fornece:

- ✅ Cotações em tempo real
- ✅ Histórico de moedas
- ✅ Sem necessidade de registro
- ✅ Sem limites de requisições (uso razoável)
- ✅ Suporte para múltiplas moedas e criptomoedas

📄 Licença

MIT

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, veja CONTRIBUTING.md.

📮 Suporte

- 🐛 Reportar Bug
- 💡 Sugerir Recurso
- 📧 Issues do GitHub

🔗 Links Úteis

- AwesomeAPI Docs
- NPM Package
- GitHub Repository

---

Feito com ❤️ no Brasil 🇧🇷