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



- ✅ 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
``bash`
npm install awesomeapi-forex
ou
`bash`
yarn add awesomeapi-forex
`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);`
`javascript
const { ForexClient } = require('awesomeapi-forex');
const client = new ForexClient();
// Uso igual ao exemplo acima
`
`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 }
})();
`
`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);`
`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);`
}
#### 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 convertidofrom
- (string) - Código da moeda de origemto
- (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 basetargetCurrency
- (string) - Código da moeda alvo
Retorna: Promise
A biblioteca suporta todas as moedas disponíveis na AwesomeAPI, incluindo:
Para ver a lista completa, visite: AwesomeAPI Docs
`bashExecutar testes
npm test
🛠️ Desenvolvimento
`bash
Instalar dependências
npm installCompilar TypeScript
npm run buildExecutar 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
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
MIT
Contribuições são bem-vindas! Por favor, veja CONTRIBUTING.md.
- 🐛 Reportar Bug
- 💡 Sugerir Recurso
- 📧 Issues do GitHub
- AwesomeAPI Docs
- NPM Package
- GitHub Repository
---
Feito com ❤️ no Brasil 🇧🇷