# IA e Postman

> Versão em Markdown da documentação pública da API v1 da Bifrost Crypto, para agentes de IA e geradores de código. Mesmo conteúdo das páginas HTML, gerado da mesma fonte, sem navegação nem estilo.
>
> Versão HTML: https://bifrostcrypto.com/pt-BR/docs/ai-and-postman
> Arquivos relacionados: [ai.md](https://bifrostcrypto.com/ai/pt-BR.md) · [Postman](https://bifrostcrypto.com/postman-collection.json) · [OpenAPI](https://bifrostcrypto.com/openapi.json) · [llms.txt](https://bifrostcrypto.com/llms.txt)
> Outros idiomas: [English](https://bifrostcrypto.com/ai/en/ai-and-postman.md) · [Español](https://bifrostcrypto.com/ai/es/ai-and-postman.md) · [Français](https://bifrostcrypto.com/ai/fr/ai-and-postman.md)
> API v1 · contrato alterado pela última vez em 2026-10-10

Dois atalhos para integrar mais rápido: uma collection do Postman para testar todos os endpoints e a documentação inteira em Markdown para agentes de IA e geradores de código.

## Collection do Postman

Todos os endpoints de /v1, com corpos de exemplo, respostas de exemplo e a autenticação já configurada. As requisições ficam em duas pastas: Read, sem efeito colateral, e Write, que cria payouts, payins e endereços fixos ou altera configuração.

Baixar collection: https://bifrostcrypto.com/postman-collection.json

No Postman, use Import e arraste o arquivo, ou cole a URL https://bifrostcrypto.com/postman-collection.json. Depois abra a aba Variables da collection e preencha apiKey.

### Variáveis da collection

| Variable | Type | Required | Description |
| --- | --- | --- | --- |
| `baseUrl` | string | opcional | URL da API, sem o /v1. Já vem preenchida. |
| `apiKey` | string | obrigatório | Sua chave de API. Vai no cabeçalho X-Bifrost-Invoke em toda requisição. |
| `signingSecret` | string | opcional | Segredo de assinatura da chave. Só para chaves criadas com assinatura de requisição; nas demais, deixe vazio. |
| `webhookUrl` | string | opcional | Seu endpoint HTTPS de webhooks, usado por Create Payout e Create Payin. Começa vazio. |
| `payoutAddress` | string | opcional | Carteira de destino de Create Payout. Começa vazia, para nada sair por engano. |
| `payoutReference · payinReference` | string | opcional | reference_id do próximo payout ou payin. Troque a cada operação nova. |
| `payoutInternalReference · payinInternalReference` | string | opcional | Preenchidas sozinhas por Create Payout e Create Payin. Usadas em Check Specific Payout e Check Specific Payin. |

> Não há sandbox público: a collection fala com a conta real da chave, e Create Payout envia fundos de verdade. payoutAddress e webhookUrl começam vazios, então um payout enviado por engano é recusado com invalid_parameters. O reference_id vem de payoutReference e payinReference: enviar a mesma requisição duas vezes é recusado como duplicado em vez de pagar duas vezes, por isso troque a variável a cada operação nova. Comece com valores pequenos.

Se a chave exige assinatura de requisição, preencha signingSecret: um script da collection acrescenta X-Bifrost-Timestamp, X-Bifrost-Nonce e X-Bifrost-Signature a toda requisição. Chaves sem assinatura ignoram essa variável.

## Documentação para IA

Agentes de IA e geradores de código leem melhor um arquivo de texto do que páginas HTML com navegação. Por isso a documentação inteira também existe em Markdown, em um único arquivo: um resumo das regras que agentes costumam errar, autenticação e assinatura de requisição, guias, webhooks e verificação de assinatura, códigos de erro, todos os endpoints com campos e exemplos, o changelog e receitas de integração.

### Arquivos

| Path | Type | Description |
| --- | --- | --- |
| `/ai.md` | `text/markdown` | A documentação inteira em inglês, com um resumo para agentes no topo e receitas de integração no fim. |
| `/ai/pt-BR.md · /ai/es.md · /ai/fr.md` | `text/markdown` | O mesmo arquivo com os guias e as explicações em cada idioma. A referência dos endpoints continua em inglês. |
| `/ai/{locale}/{page}.md` | `text/markdown` | Uma única página desta documentação, por exemplo https://bifrostcrypto.com/ai/pt-BR/create-payout-single.md. |
| `/llms.txt` | `text/plain` | Índice curto no padrão llms.txt, que ferramentas de IA procuram na raiz do site. Aponta para os arquivos acima. |
| `/postman-collection.json` | `application/json` | Collection do Postman v2.1. |
| `/openapi.json` | `application/json` | Especificação OpenAPI 3.1, gerada da mesma fonte. |

## Usando com um assistente

Passe ao assistente a URL do arquivo Markdown e descreva o que quer integrar. Alguns pontos de partida:

**Receber pagamentos**

```text
Leia a documentação da API em https://bifrostcrypto.com/ai/pt-BR.md.
Implemente no meu backend:
1. a criação de um payin para um pedido, usando o id do pedido como reference_id e guardando o internal_reference;
2. um endpoint de webhook que valide X-Bifrost-Signature sobre o corpo cru, responda 2xx na hora e dê baixa no pedido em payment_confirmed depois de comparar received_amount com crypto_amount.
Leia a chave da API da variável de ambiente BIFROST_API_KEY e a chave de webhook de BIFROST_WEBHOOK_KEY.
```

**Enviar payouts**

```text
Leia a documentação da API em https://bifrostcrypto.com/ai/pt-BR.md.
Implemente uma rotina de payout que envie até 50 payouts por requisição para POST /v1/payout, com um reference_id estável por payout e um Idempotency-Key por requisição. Leia results[] pelo index, guarde o internal_reference dos itens criados e reenvie só os recusados, decidindo pelo error.code.
Leia a chave da API da variável de ambiente BIFROST_API_KEY.
```

**Endereço fixo por cliente**

```text
Leia a documentação da API em https://bifrostcrypto.com/ai/pt-BR.md.
Implemente um endereço fixo de depósito por cliente com POST /v1/fixed-wallets, usando o nosso id de cliente como customer_info, e um handler de webhook que credite o cliente em payment_confirmed nos depósitos com is_wallet_fixed true.
Leia a chave da API da variável de ambiente BIFROST_API_KEY e a chave de webhook de BIFROST_WEBHOOK_KEY.
```

> Nunca cole a chave da API, o segredo de assinatura ou a chave de webhook no chat de um assistente. Diga a ele para ler de variáveis de ambiente.