POST

Create Fixed Wallet

La référence de l'API est en anglais. Les guides, l'authentification, les webhooks et les codes d'erreur sont en français.

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

Portée requise :wallets:write(une clé nouvelle sans liste est en lecture seule)

La Permission du Gardien est Requise

"Tout voyageur ne peut ériger une porte éternelle. Pour tenir un portail ouvert et veiller sur son seuil sans repos, le gardien vigilant doit d'abord accorder sa bénédiction : implore Heimdall, et alors seulement ta pierre runique perdurera."

Heimdallr Níu-mæðra sonr

ᚱ

"Tous les ponts ne sont pas éphémères. Certaines portes sont taillées dans la pierre éternelle des royaumes, inébranlables à chaque hiver, un passage permanent par lequel une seule âme pourra toujours traverser."

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.

Autres réponses

Réponses qui ne sont pas le chemin nominal et qui doivent malgré tout être traitées dans votre intégration.

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

Avertissement Ancestral des Gardiens

"Prends garde, voyageur : une porte permanente, une fois liée à une âme, ne répond qu'à cette âme. N'érige pas plus de pierres que le pacte ne le permet, de peur que le puits des portails éternels ne se tarisse."

Les Gardiens du Bifrost