POST

Create Fixed Wallet

La referencia de la API está en inglés. Las guías, la autenticación, los webhooks y los códigos de error están en español.

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

Alcance requerido:wallets:write(una clave nueva sin lista es de solo lectura)

Se Requiere el Permiso del Guardián

"No todo viajero puede erigir una puerta eterna. Para mantener un portal abierto y vigilar su umbral sin descanso, el guardián vigilante debe primero conceder su bendición: implora a Heimdall, y solo entonces perdurará tu piedra rúnica."

Heimdallr Níu-mæðra sonr

ᚱ

"No todos los puentes son efímeros. Algunas puertas están talladas en la piedra eterna de los reinos, inmutables ante cada invierno, un umbral permanente por el que una sola alma siempre podrá 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.

Otras respuestas

Respuestas que no son el camino feliz y aun así necesitan tratamiento en su integración.

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"
  }
}

Advertencia Ancestral de los Guardianes

"Ten cuidado, viajero: una puerta permanente, una vez ligada a un alma, responde solo a esa alma. No erijas más piedras de las que el pacto permite, para que el pozo de los portales eternos no se agote."

Los Guardianes del Bifrost