POST

Create Fixed Wallet

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

Required scope:wallets:write(a new key with no list is read-only)

Permission of the Guardian Required

"Not every traveler may raise an eternal gate. To hold a portal open and watch its threshold without rest, the vigilant guardian must first grant his blessing: beseech Heimdall, and only then shall your standing stone endure."

Heimdallr Níu-mæðra sonr

ᚱ

"Not all bridges are ephemeral. Some gates are carved into the eternal stone of the realms, standing unshaken through every winter, a permanent doorway through which a single soul may always cross."

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.

Other responses

Responses that are not the happy path and still need handling in your integration.

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

Ancestral Warning from the Guardians

"Beware, traveler: a permanent gate, once bound to a soul, answers to that soul alone. Do not raise more stones than the covenant allows, lest the pool of eternal portals run dry."

The Guardians of Bifrost