POST

Create Fixed Wallet

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.

POSThttps://bridge.bifrostcrypto.com/v1/fixed-wallets

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

É Preciso a Permissão do Guardião

"Nem todo viajante pode erguer um portão eterno. Para manter um portal aberto e vigiar o seu limiar sem descanso, o guardião vigilante deve primeiro conceder a sua bênção: implore a Heimdall, e só então a sua pedra rúnica perdurará."

Heimdallr Níu-mæðra sonr

ᚱ

"Nem toda ponte é efêmera. Alguns portões são esculpidos na pedra eterna dos reinos, imóveis diante de todos os invernos, uma passagem permanente pela qual uma única alma sempre poderá cruzar."

Heimdallr Níu-mæðra sonr

Headers

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

Body Parameters

Field	Type	Description
`type`required	`string`	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"
  }
}

Advertência Ancestral dos Guardiões

"Cuidado, viajante: um portão permanente, uma vez atado a uma alma, responde somente a essa alma. Não ergas mais pedras do que o pacto permite, para que o poço dos portais eternos não se esgote."

Os Guardiões do Bifrost