# Create Fixed Wallet

> 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/create-fixed-wallet
> 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/create-fixed-wallet.md) · [Español](https://bifrostcrypto.com/ai/es/create-fixed-wallet.md) · [Français](https://bifrostcrypto.com/ai/fr/create-fixed-wallet.md)
> API v1 · contrato alterado pela última vez em 2026-10-10

`POST https://bridge.bifrostcrypto.com/v1/fixed-wallets`

Escopo exigido: `wallets:write` (chave nova sem lista é somente leitura)

> A referência da API está em inglês. Os guias, a autenticação, os webhooks e os códigos de erro estão em português.

Assigns a fixed (permanent) address to your account for the given chain family (type).

A single address serves every network of the same family (e.g. an evm address works across all EVM networks). A new assignment answers 201 with fixed_wallets_assign_success. If customer_info is provided and already has an active (STATUS_ASSIGNED) address of the same type, the existing one is returned with 200 and fixed_wallets_already_assigned. That reuse check ignores origin, so it can return an address created in the panel (origin: panel), which List Fixed Wallets does not show. The reuse is checked before the limits, so it never consumes allowance.

## Headers

| Key | Value | Description |
| --- | --- | --- |
| `X-Bifrost-Invoke` | `{{api_key}}` | Private API key |
| `Content-Type` | `application/json` | - |

## Body Parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | required | Chain family enabled for fixed addresses (e.g.: evm, tron, solana, bitcoin). See the type field in Supported Networks. Max 20 chars, case-insensitive. |
| `customer_info` | `string` | - | Customer identifier (no spaces, max 255). Enables idempotent reuse of the same address per customer. |

## Request Body

```json
{
  "type": "evm",
  "customer_info": "customer123"
}
```

## cURL Example

```bash
curl -X POST "https://bridge.bifrostcrypto.com/v1/fixed-wallets" \
  -H "X-Bifrost-Invoke: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "evm",
  "customer_info": "customer123"
}'
```

## Response Example

```json
{
  "message": "fixed_wallets_assign_success",
  "wallet": {
    "customer_info": "customer123",
    "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
    "type": "evm",
    "status": "STATUS_ASSIGNED",
    "origin": "external_api",
    "last_transaction_at": null,
    "created_at": "2026-01-16 10:00:00",
    "updated_at": "2026-01-16 10:00:00",
    "networks": [
      "Ethereum",
      "BinanceSmartChain"
    ],
    "accepted_tokens": [
      {
        "network": "Ethereum",
        "token": "USDT",
        "symbol": "USDT"
      }
    ],
    "pending_revocation": false,
    "revoke_at": null
  }
}
```

## Receiving on a fixed address

Each transfer to a fixed address creates a new payin, already completed, and sends payment_detected / payment_confirmed to the fixed-address webhook URL. That URL is set in the panel (it can also be set with PUT /v1/fixed-wallets/config); without it no notice is sent. The payin has a generated reference_id (equal to internal_reference), is_wallet_fixed: true and the customer_info of the address, so match the deposit to your customer by customer_info or wallet. Payins from addresses created through the API are also returned by List Payins and Check Specific Payin. Transfers worth less than 0.01 in fiat are ignored.

```json
{
  "event": "payment_confirmed",
  "timestamp": "2026-03-01 12:03:00",
  "data": {
    "status": "success",
    "funds_available": true,
    "finality_status": "final",
    "wallet": "0x742d35cc6634c0532925a3b844bc9e7595f0beb0",
    "customer_info": "customer123",
    "network": "BinanceSmartChain",
    "crypto_currency": "USDT",
    "crypto_amount": "25.00000000",
    "received_amount": "25.00000000",
    "reference_id": "8d1f3a52-6c0e-4b7a-9f21-3e5d7c9a0b14",
    "internal_reference": "8d1f3a52-6c0e-4b7a-9f21-3e5d7c9a0b14",
    "is_wallet_fixed": true,
    "is_duplicated": false,
    "...": "..."
  }
}
```

## Errors

Every error has the shape error.code, error.message and, when useful, error.details. Authentication, scope and rate-limit errors (401, 403, 429) apply to every endpoint and are described under Authentication.

| Status | Code | When | What to do |
| --- | --- | --- | --- |
| `400` | `invalid_parameters` | type missing or longer than 20, or customer_info with spaces or longer than 255; details.fields. | Fix the request before sending it again. |
| `403` | `feature_disabled` | Fixed addresses are not enabled for the account. | Contact support. |
| `403` | `limit_not_allowed` | Your limit for this type is zero, or the type is not in your per-type map. | Contact support. |
| `409` | `limit_reached` | You already hold the maximum number of fixed addresses. | Check allowance in List Fixed Wallets. |
| `409` | `no_wallet_available` | No address of that type is available right now. | Nothing was changed. Retry later. |
| `422` | `type_not_supported` | type is not listed in Supported Networks. | Fix the request before sending it again. |
| `500` | `assign_failed` | The address could not be assigned. | Nothing was changed. Retry later. |
| `502` | `external_processor_error` | The address could not be created right now. | Nothing was changed. Retry later. |

## Outras respostas

Respostas que não são o caminho feliz e ainda assim precisam de tratamento na sua integração.

### 200 · Existing address reused

The same customer_info and chain family returns the address already assigned. A new assignment uses the body above with HTTP 201.

```json
{
  "message": "fixed_wallets_already_assigned",
  "wallet": {
    "customer_info": "customer123",
    "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
    "type": "evm",
    "status": "STATUS_ASSIGNED",
    "origin": "external_api",
    "last_transaction_at": "2026-02-03 18:21:07",
    "created_at": "2026-01-16 10:00:00",
    "updated_at": "2026-02-03 18:21:07",
    "networks": [
      "Ethereum",
      "BinanceSmartChain"
    ],
    "accepted_tokens": [
      {
        "network": "Ethereum",
        "token": "USDT",
        "symbol": "USDT"
      }
    ],
    "pending_revocation": false,
    "revoke_at": null
  }
}
```

### 409 · Limit reached

Other refusals: 400 invalid_parameters (type missing or longer than 20, customer_info with spaces or longer than 255; details.fields), 403 feature_disabled, 422 type_not_supported (type not listed in Supported Networks), 403 limit_not_allowed (limit 0, or type missing from the per-type map), 409 limit_reached, 409 no_wallet_available (no address of that type is available right now; retry later), 500 assign_failed, 502 external_processor_error (the address could not be created right now; retry later).

```json
{
  "error": {
    "code": "limit_reached",
    "message": "Fixed address limit reached"
  }
}
```