Documentação - Bifrost API

The Nine Blockchain Realms

"Through the rainbow bridge of Bifrost, nine digital realms connect, each guarding ancestral secrets of blockchain technology. Heimdall watches the passages between worlds, allowing only the worthy to cross the sacred portals."

Warning from Asgard's Guardians

By decree of the High Sages of Asgard, seven of the nine sacred realms are shrouded in the mists of time, their portals sealed with ancestral runes while Heimdall strengthens the interdimensional bridges. Only the luminous Realm of Alfheim (Binance Smart Chain) and the mysterious Realm of Svartalfheim (Polygon) remain accessible to worthy mortals. May your journey through the golden paths and the dark elves' forges be prosperous, until the cosmic winds blow again and the other portals are reopened by the will of the gods.

The Nine Realms and Their Mythical Correspondences

Sealed

Bitcoin - Asgard

The Realm of the Gods, where Odin resides

Sealed

Ethereum - Midgard

The Realm of Mortals, center of all activity

Active

Binance Smart Chain - Alfheim

Realm of the Light Elves, fast and bright

Sealed

Optimism - Ljosalfgard

Realm of the Luminous Elves, optimism and speed

Sealed

Arbitrum - Vanaheim

Realm of the Vanir, wisdom and scalability

Sealed

Cronos - Jotunheim

Realm of the Giants, colossal power and speed

Sealed

Avalanche - Niflheim

Realm of Frozen Mists, avalanche consensus

Active

Polygon - Svartalfheim

Realm of the Dark Elves, solution forgers

Sealed

Base - Muspelheim

Realm of Primordial Fire, incandescent energy

Coins of the Mortal Realms

"In the golden chambers of mortal realms, each coin carries the ancestral power of its homeland, forged with the wisdom of the ancients and blessed by celestial guardians."

Ancestral Warning from the Guardians

The mortal realm currencies (BRL, USD, EUR, etc.) are merely ethereal mirrors used by the oracles to calculate conversions between worlds. These currencies are NOT directly accepted in Asgard's sacred vaults. Only the divine tokens of the nine blockchain realms can cross the Bifrost bridges and be deposited in the celestial coffers.

ARS - Pesos of the Argentine Realm

Born from the winds of infinite pampas

AUD - Dollars of the Australian Realm

Tempered by the winds of the mystical outback

BRL - Gold of the Brazilian Kingdom

Forged in the sacred mines of the Amazon

CAD - Dollars of the Canadian Realm

Crystallized in the eternal glaciers of the north

CHF - Francs of the Swiss Realm

Sculpted in the sacred Alpine peaks

EUR - Coins of the European Realm

Molded in the union of ancestral realms

GBP - Pounds of the Britannia Realm

Guarded by dragons of the mystical islands

INR - Rupees of the Indian Realm

Minted in Bharat’s bazaars, scented with ancestral spices

JPY - Yen of the Rising Sun Realm

Illuminated by the aurora of eternal samurai

MXN - Pesos of the Mexican Realm

Blessed by Aztec spirits

THB - Bahts of the Thai Realm

Forged on the banks of the Chao Phraya, consecrated in gilded pagodas

USD - Silver of the American Empire

Minted in the temples of eternal freedom

Heimdall's Seal

"In the mists of Niflheim, only bearers of the golden seal can cross the digital rainbow bridges."

To cross the sacred portals of Bifrost, worthy mortals must carry the Access Rune, a mystical seal inscribed in the headers of all invocations to the nine realms.

The Ancestral Access Rune

In each call to the sacred portals, present the Access Rune in the mystical header:

X-Bifrost-Invoke: your_access_rune_to_the_bifrost

The Invocation Rune

This sacred header must accompany all your requests to the nine realms. Replace your_access_rune_to_the_bifrost with your personal rune, forged in the halls of Asgard and granted by the divine guardians.

Mystical Rune Example

curl -X GET "https://bridge.bifrostcrypto.com/endpoint" \
  -H "X-Bifrost-Invoke: your_access_rune_to_the_bifrost" \
  -H "Content-Type: application/json"

Request Limits

"The guardians of Heimdall monitor every passage across the rainbow bridge. Each Sacred Access Rune has its own crossing limit. Those who attempt to cross excessively will be temporarily prevented."

Sacred Rules of Limits

Default Limit

1.000 requests per minute per Sacred Rune

🚫 When Limit is Exceeded

If you exceed the limit, you will receive HTTP code 429:

HTTP/1.1 429 Too Many Requests

{
  "error": "limit_exceeded_for_rune"
}

Global Realms Summary

"In the halls of knowledge of Asgard, the global summary reveals all secrets: tokens accepted by the gods, currencies recognized by the nine realms and the sacred configurations of the divine portals."

GET

/external/summary

Reveals the complete wisdom of the nine realms: accepted tokens, fiat currencies and configurations.

Ancestral Warning from the Guardians

Wisdom of the Nine Realms200

{
    "message": "summary_retrieved_success",
    "data": {
        "accepted_tokens": [
            {
                "symbol": "ETH",
                "contract_address": null,
                "network": "Ethereum",
                "min_receipt": 0.001,
                "max_receipt": 9.223372036854776e+18,
                "min_withdrawal": 0.001,
                "max_withdrawal": 9.223372036854776e+18,
                "network_fee": 0.0005
            },
            {
                "symbol": "USDT",
                "contract_address": "0x55d398326f99059fF775485246999027B3197955",
                "network": "BinanceSmartChain",
                "min_receipt": 2,
                "max_receipt": 1000000000,
                "min_withdrawal": 2,
                "max_withdrawal": 1000000000,
                "network_fee": 0.5
            }
        ],
        "accepted_fiats": [
            {
                "code": "BRL",
                "name": "Brazilian Real",
                "symbol": "R$"
            },
            {
                "code": "USD",
                "name": "US Dollar",
                "symbol": "$"
            }
        ],
        "user_info": {
            "minimum_payment": 99.9,
            "receipt_rate": 5,
            "payment_rate": 2,
            "deposit_rate": 0.5,
            "withdrawal_rate": 0.5,
            "user_pays_payment_network_fee": false,
            "user_pays_receipt_network_fee": false,
            "user_pays_deposit_network_fee": false,
            "user_pays_withdrawal_network_fee": false
        },
        "summary_stats": {
            "total_tokens": 11,
            "total_fiats": 11,
            "generated_at": "2025-09-07 19:33:37"
        }
    }
}

GET

/external/summary/tokens

Queries only the tokens accepted by the gods of the nine realms.

Sacred Tokens200

{
    "message": "tokens_retrieved_success",
    "tokens": [
        {
            "symbol": "ETH",
            "contract_address": null,
            "network": "Ethereum",
            "min_receipt": 0.001,
            "max_receipt": 9.223372036854776e+18,
            "min_withdrawal": 0.001,
            "max_withdrawal": 9.223372036854776e+18,
            "network_fee": 0.0005
        },
        {
            "symbol": "BNB",
            "contract_address": null,
            "network": "BinanceSmartChain",
            "min_receipt": 0.001,
            "max_receipt": 100000,
            "min_withdrawal": 0.001,
            "max_withdrawal": 100000,
            "network_fee": 0.0005
        },
        {
            "symbol": "USDT",
            "contract_address": "0x55d398326f99059fF775485246999027B3197955",
            "network": "BinanceSmartChain",
            "min_receipt": 2,
            "max_receipt": 1000000000,
            "min_withdrawal": 2,
            "max_withdrawal": 1000000000,
            "network_fee": 0.5
        },
        {
            "symbol": "USDC",
            "contract_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
            "network": "Ethereum",
            "min_receipt": 2,
            "max_receipt": 1000000000,
            "min_withdrawal": 2,
            "max_withdrawal": 1000000000,
            "network_fee": 1.0e-5
        }
    ],
    "meta": {
        "total": 11,
        "generated_at": "2025-09-07 19:35:32"
    }
}

GET

/external/summary/fiats

Reveals the fiat currencies accepted by Asgard's vaults, with their symbols and sacred denominations.

Realms Coins200

{
    "message": "fiats_retrieved_success",
    "fiats": [
        {
            "code": "BRL",
            "name": "Brazilian Real",
            "symbol": "R$"
        },
        {
            "code": "USD",
            "name": "US Dollar",
            "symbol": "$"
        },
        {
            "code": "EUR",
            "name": "Euro",
            "symbol": "€"
        },
        {
            "code": "GBP",
            "name": "British Pound",
            "symbol": "£"
        },
        {
            "code": "ARS",
            "name": "Argentine Peso",
            "symbol": "$"
        },
        {
            "code": "MXN",
            "name": "Mexican Peso",
            "symbol": "$"
        },
        {
            "code": "CAD",
            "name": "Canadian Dollar",
            "symbol": "CA$"
        },
        {
            "code": "AUD",
            "name": "Australian Dollar",
            "symbol": "A$"
        },
        {
            "code": "CHF",
            "name": "Swiss Franc",
            "symbol": "CHF"
        },
        {
            "code": "JPY",
            "name": "Japanese Yen",
            "symbol": "¥"
        },
        {
            "code": "CNY",
            "name": "Chinese Yuan",
            "symbol": "¥"
        },
        {
            "code": "INR",
            "name": "Indian Rupee",
            "symbol": "₹"
        },
        {
            "code": "THB",
            "name": "Thai Baht",
            "symbol": "฿"
        }
    ],
    "meta": {
        "total": 13,
        "generated_at": "2025-09-07 19:38:19"
    }
}

Treasures of Asgard

"In the sacred vaults of Asgard, Heimdall guards the digital treasures of each realm. Query the balances to reveal the riches accumulated in your journey through the nine worlds."

GET

/external/balances

Query the sacred vaults of Asgard to reveal all balances of divine tokens in your possession.

Balance Query

curl -X GET "https://bridge.bifrostcrypto.com/external/balances" \
  -H "X-Bifrost-Invoke: your_access_rune_to_the_bifrost"

Treasures Revealed200

{
    "message": "balances_retrieved_success",
    "balances": {
        "balance_bitcoin": "10000.00000000",
        "balance_ethereum": "10000.00000000",
        "balance_tether": "9995.84000000",
        "balance_usdcoin": "10000.00000000",
        "balance_binancecoin": "10000.00000000",
        "balance_cardano": "10000.00000000",
        "balance_solana": "10000.00000000",
        "balance_matic": "10000.00000000",
        "balance_tron": "10000.00000000",
        "created_at": "2021-08-19 15:03:29",
        "updated_at": "2021-08-19 15:03:29"
    }
}

Statement Scrolls

"In the ancestral archives of Valhalla, every movement between realms is eternally recorded. The statement scrolls reveal the complete history of your journey through the nine digital worlds."

GET

/external/statements

Invoke the ancestral scrolls to list all movements with advanced filters from the nine realms.

Query with Filters

curl -X GET "https://bridge.bifrostcrypto.com/external/statements?page=1&limit=10&date_from=2024-01-01&date_to=2024-01-31" \
  -H "X-Bifrost-Invoke: your_access_rune_to_the_bifrost"

Ancestral Scrolls200

{
    "message": "statements_retrieved_success",
    "statements": [
        {
            "direction": "out",
            "type": "RATE",
            "reference_id": "PAY-001-2024",
            "amount": 0.04,
            "balance": "balance_tether",
            "internal_reference": "a0da563a-a0a5-49d3-a792-d360399b05a5",
            "created_at": "2025-09-07 19:11:44",
            "updated_at": "2025-09-07 19:11:44"
        },
        {
            "direction": "out",
            "type": "WITHDRAWAL",
            "reference_id": "PAY-001-2024",
            "amount": 2,
            "balance": "balance_tether",
            "internal_reference": "a0da563a-a0a5-49d3-a792-d360399b05a5",
            "created_at": "2025-09-07 19:11:44",
            "updated_at": "2025-09-07 19:11:44"
        }
    ],
    "filters": [],
    "meta": {
        "current_page": 1,
        "per_page": 50,
        "total": 2,
        "total_pages": 1
    }
}

Scroll Invocation Runes

GET

/external/statements/summary

Returns a statistical summary of statements.

Query Example

curl -X GET "https://bridge.bifrostcrypto.com/external/statements/summary" \
  -H "X-Bifrost-Invoke: your_access_rune_to_the_bifrost"

Statements Summary200

{
  "message": "statement_summary_retrieved_success",
  "summary": {
    "total_statements": 1247,
    "by_direction": {
      "in": 658,
      "out": 589
    },
    "by_type": {
      "deposits": 520,
      "withdrawals": 489,
      "fees": 98,
      "rates": 140,
      "royalties": 0,
      "exchanges": 0
    },
    "recent_activity": 45
  }
}

Prices and Conversions

"The Oracle of Mimir knows the value of every currency in the nine realms. Consult it to know the exchange rates between digital and mortal worlds."

GET

/external/get-price

Gets the conversion price between two currencies (crypto or fiat).

Query Parameters

Field	Type	Description
`currency1`	string	Source currency (BTC, ETH, USDT, BRL, USD, etc)
`currency2`	string	Target currency (BTC, ETH, USDT, BRL, USD, etc)

Query Example

curl -X GET "https://bridge.bifrostcrypto.com/external/get-price?currency1=USDT&currency2=BRL" \
  -H "X-Bifrost-Invoke: your_access_rune_to_the_bifrost"

Oracle Response200

{
  "success": true,
  "data": {
    "from": "USDT",
    "to": "BRL",
    "price": "5,40",
    "type": "crypto_to_fiat",
    "last_updated": "2025-10-05T10:30:00-03:00"
  }
}

Conversion Examples

GET /external/get-price?currency1=BTC&currency2=USD

Returns the price of 1 BTC in USD

GET /external/get-price?currency1=ETH&currency2=BTC

Returns how much 1 ETH is worth in BTC

GET /external/get-price?currency1=USD&currency2=BRL

Returns the USD/BRL exchange rate

GET

/external/get-currencies

Lists all available currencies for conversion.

Query Example

curl -X GET "https://bridge.bifrostcrypto.com/external/get-currencies" \
  -H "X-Bifrost-Invoke: your_access_rune_to_the_bifrost"

Available Currencies200

{
  "success": true,
  "data": {
    "currencies": [
      {
        "currency": "BRL",
        "name": "Real Brasileiro",
        "type": "fiat"
      },
      {
        "currency": "USD",
        "name": "Dólar Americano",
        "type": "fiat"
      },
      {
        "currency": "BTC",
        "name": "BTC",
        "type": "crypto"
      },
      {
        "currency": "ETH",
        "name": "ETH",
        "type": "crypto"
      },
      {
        "currency": "USDT",
        "name": "USDT",
        "type": "crypto"
      }
    ],
    "total": 5
  }
}

Creating Divine Payments

"In Heimdall's forge, payments are molded with the precision of SVARTALFHEIM's dwarves. Each transaction carries the strength of Mjolnir and the wisdom of Odin."

POST

/external/payout

Invoke the sacred runes to create instant payments across the nine blockchain realms.

Payment Example

[{
  "crypto_currency": "USDT",
  "process_by": "crypto_amount", 
  "reference_id": "PAY-001-2024",
  "crypto_amount": "100.50",
  "network": "Ethereum",
  "wallet": "0x742d35Cc1D1B2F48dE3D7d8c53c4E7Db0C4bC123",
  "webhook_url": "https://your-domain.com/webhook/payment"
}]

Divine Forge Response200

{
    "message": "payment_processing_completed",
    "summary": {
        "total_requested": 1,
        "successful": 1,
        "failed": 0
    },
    "results": [
        {
            "index": 0,
            "reference_id": "PAY-001-2024",
            "internal_reference": "a0da563a-a0a5-49d3-a792-d360399b05a5",
            "crypto_amount": 2,
            "fiat_amount": null,
            "crypto_currency": "USDT",
            "fiat_currency": null,
            "network_fee": 0.5,
            "wallet": "0x742d35Cc1D1B2F48dE3D7d8c53c4E7Db0C4bC123",
            "network": "BinanceSmartChain",
            "process_by": "crypto_amount",
            "status": "created"
        }
    ]
}

Listing Payments

GET

/external/list-payout

Query Asgard's records to list all completed payments.

Query Example

curl -X GET "https://bridge.bifrostcrypto.com/external/list-payout?page=1&per_page=10&status=pending" \
  -H "X-Bifrost-Invoke: your_access_rune_to_the_bifrost"

Forge Records200

{
    "message": "payments_retrieved_success",
    "payments": [
        {
            "internal_reference": "a0da563a-a0a5-49d3-a792-d360399b05a5",
            "reference_id": "PAY-001-2024",
            "wallet": "0x742d35Cc1D1B2F48dE3D7d8c53c4E7Db0C4bC123",
            "crypto_currency": "USDT",
            "fiat_currency": null,
            "crypto_amount": "2.000000000000000000",
            "fiat_amount": null,
            "process_by": "crypto_amount",
            "percent_rate": "2.00",
            "network_fee": "0.50000000",
            "network": "BinanceSmartChain",
            "status": "WITHDRAWAL_STATUS_PENDING",
            "txid": null,
            "webhook_url": "https://01k1xtw4kcy8ht2tecj848ts1b.hooks.webhookrelay.com",
            "feetakenfromamount": "0",
            "created_at": "2025-09-07 19:11:44",
            "updated_at": "2025-09-07 19:11:44",
            "expires_at": "2025-09-07 20:11:44"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 50,
        "total": 1,
        "total_pages": 1
    }
}

Records Consultation Runes

Creating Receipts

"In the golden halls of Valhalla, each receipt is a sacred scroll sealed with the runes of the nine realms."

POST

/external/payin

Invoke ancestral magic to create receipt portals with expiration time configurable by the gods.

Receipt Example

[{
  "crypto_currency": "USDT",
  "process_by": "crypto_amount",
  "reference_id": "REC-CRYPTO-001-2024",
  "crypto_amount": "100.50",
  "network": "Ethereum",
  "webhook_url": "https://your-domain.com/webhook/receipt",
  "fiat_currency": "USD",
  "expires_at": 3600
}]

Ancestral Magic Response200

{
    "message": "deposit_processing_completed",
    "summary": {
        "total_requested": 1,
        "successful": 1,
        "failed": 0
    },
    "results": [
        {
            "reference_id": "REC-CRYPTO-001-2024",
            "internal_reference": "7e6728f1-63ba-4d59-b489-673d90fa6b1e",
            "wallet": "0xcdC8aF299Ce76B1cD489928Ed76D1Efdb6E5A589",
            "crypto_amount": 100.5,
            "fiat_amount": null,
            "crypto_currency": "USDT",
            "fiat_currency": "USD",
            "network": "BinanceSmartChain",
            "status": "created"
        }
    ]
}

Listing Receipts

GET

/external/list-payin

Query Valhalla's sacred archives to list all receipts.

Query Example

curl -X GET "https://bridge.bifrostcrypto.com/external/list-payin?page=1&per_page=10&status=pending" \
  -H "X-Bifrost-Invoke: your_access_rune_to_the_bifrost"

Valhalla Treasures200

{
    "message": "deposits_retrieved_success",
    "deposits": [
        {
            "internal_reference": "7e6728f1-63ba-4d59-b489-673d90fa6b1e",
            "reference_id": "REC-CRYPTO-001-2024",
            "wallet": "0xcdC8aF299Ce76B1cD489928Ed76D1Efdb6E5A589",
            "crypto_currency": "USDT",
            "fiat_currency": "USD",
            "crypto_amount": "100.50000000",
            "received_amount": null,
            "fiat_amount": null,
            "process_by": "crypto_amount",
            "percent_rate": "5.00",
            "network_fee": "0.50000000",
            "minimum_payment": "99.90",
            "network": "BinanceSmartChain",
            "status": "INVOICE_STATUS_PENDING",
            "status_message": "pending_status",
            "txid": null,
            "webhook_url": "https://your-domain.com/webhook/receipt",
            "created_at": "2025-09-07 19:30:19",
            "updated_at": "2025-09-07 19:30:19",
            "expires_at": "2025-09-07 20:30:19"
        }
    ],
    "summary": {
        "total_pending": 1,
        "total_completed": 0,
        "total_failed": 0
    },
    "meta": {
        "current_page": 1,
        "per_page": 50,
        "total": 1,
        "total_pages": 1,
        "filters": []
    }
}

Treasures Consultation Runes

Complete Query Example

?status=COMPLETED&crypto_currency=USDT&network=Ethereum&date_from=2024-01-01&reference_id=DEP123

Querying Receipt

GET

/external/check-payin/{internal_reference}

Invoke Heimdall's oracle to query a specific receipt.

Querying Payment

GET

/external/check-payout/{internal_reference}

Invoke Heimdall's oracle to query a specific payment.

Heimdall's Messengers - Webhooks

Odin's ravens, Huginn and Muninn, fly through the nine realms carrying instant news. Such are our webhooks - divine messengers that inform about every movement on the Bifrost bridges.

Types of Divine Messages

Receipt Processed (Payin)

Sent when a payment is received and successfully confirmed in the sacred vaults.

{
  "event": "payment_confirmed",
  "timestamp": "2024-01-15 14:30:25",
  "data": {
    "status": "success",
    "wallet": "0x1234567890abcdef1234567890abcdef12345678",
    "created_at": "2024-01-15 14:25:10",
    "network": "BinanceSmartChain",
    "fiat_amount": "100.00",
    "network_fee": "0.00050000",
    "confirmed_at": "2024-01-15 14:30:20",
    "percent_rate": "2.50",
    "reference_id": "REF123456",
    "transactions": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "crypto_amount": "0.25000000",
    "received_amount": "0.25000000",
    "fiat_currency": "BRL",
    "crypto_currency": "BNB",
    "internal_reference": "INT_REF_789"
  }
}

Payment Confirmed (Payout)

Notification sent when a payment successfully crosses the Bifrost bridge and is confirmed on the blockchain.

{
  "event": "payment_processed",
  "timestamp": "2024-01-15 14:30:25",
  "data": {
    "status": "success",
    "reference_id": "REF123456",
    "internal_reference": "INT_REF_789",
    "wallet": "0x1234567890abcdef1234567890abcdef12345678",
    "created_at": "2024-01-15 14:25:10",
    "network": "BinanceSmartChain",
    "fiat_amount": "100.00",
    "network_fee": "0.00050000",
    "confirmed_at": "2024-01-15 14:30:20",
    "percent_rate": "2.50",
    "transactions": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "crypto_amount": "0.25000000",
    "fiat_currency": "BRL",
    "crypto_currency": "BNB"
  }
}

Payment Failed

Message sent when Loki interferes and a transaction cannot be completed.

{
  "event": "payment_failed",
  "timestamp": "2024-01-15 14:30:25",
  "data": {
    "status": "failed",
    "reference_id": "REF123456",
    "internal_reference": "INT_REF_789"
  }
}

Headers Sent in Webhooks

All webhooks are sent with special headers for validation and identification:

POST /sua-url-webhook HTTP/1.1
Host: sua-api.exemplo.com
Content-Type: application/json
User-Agent: Bifrost/1.0
X-Bifrost-Webhook-Type: payment_processed
X-Bifrost-Timestamp: 1728138000
X-Bifrost-Version: 1.0
X-Bifrost-Signature: a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890
X-IPN-Secret: your_divine_unique_code

Header Explanation

Field	Description
`X-Bifrost-Webhook-Type`	Event type (payment_processed, payment_confirmed, etc)
`X-Bifrost-Timestamp`	Unix timestamp of sending moment
`X-Bifrost-Version`	Bifrost API version
`X-Bifrost-Signature`	HMAC-SHA256 signature for validation
`X-IPN-Secret`	Your divine secret code for verification

Validating Signature

Always validate the webhook signature to ensure the message is authentic:

<?php
$payload = file_get_contents('php://input');
$receivedSignature = $_SERVER['HTTP_X_BIFROST_SIGNATURE'];
$ipnSecret = 'your_divine_unique_code';

$calculatedSignature = hash_hmac('sha256', $payload, $ipnSecret);

if (!hash_equals($calculatedSignature, $receivedSignature)) {
    http_response_code(401);
    exit('Assinatura inválida');
}

// Webhook válido - processar payload
$data = json_decode($payload, true);

Retry System

If your webhook fails, Bifrost will automatically retry:

Attempt	Delay after failure
1ª	Immediate
2ª	1 minute
3ª	5 minutes
4ª	15 minutes
5ª	1 hour
6ª	4 hours

Important Warning After 6 unsuccessful attempts, the webhook is marked as failed.

The Sacred Seal of Authenticity

The Secret Seal of Divine Receipts

The Legend of the Runic Code:

When merchants from the nine realms send their offerings through Bifrost, Heimdall, the golden-eyed guardian, inscribes a unique secret code in the header of each message. This mystical seal travels through the X-IPN-Secret header, an ancestral rune that only you and the gods know.

The Sacred Header

X-IPN-Secret: your_divine_unique_code

Power of the Rune

Each code is forged in the forges of SVARTALFHEIM, unique and non-transferable, impossible to counterfeit by the giants of chaos.

Divine Protection

Only messages that carry this sacred seal in the header are accepted in the halls of Valhalla, ensuring your treasures are always protected.

Heimdall's Oath:

"This seal in the X-IPN-Secret header guarantees that the message legitimately crossed the rainbow bridge, coming directly from Bifrost's sacred coffers, and not from malicious entities trying to deceive the guardians of treasures."

Elders' Warning: Guard this code as your greatest treasure. Not even Odin's ravens should know it. Configure it in your control panel and validate the X-IPN-Secret header in every message received.

Message Fields

Field	Type	Description
`event`	string	Event type: payment_processed, payment_confirmed, payment_failed
`timestamp`	datetime	Exact moment of the event in temporal realms
`status`	string	Transaction status: success or failed
`reference_id`	string	Your unique transaction reference
`internal_reference`	string	Bifrost internal reference
`wallet`	string	Involved wallet address
`transactions`	string	Blockchain transaction hash
`crypto_amount`	string	Cryptocurrency amount
`received_amount`	string	Amount received after fees (in Payins)
`fiat_amount`	string	Fiat currency amount

The Sacred Header

X-IPN-Secret Header - Gods' authenticity seal sent in the header of all webhooks

X-IPN-Secret: your_divine_unique_code

Error Codes

"When the forces of chaos interfere, the gods send clear messages to mortals. Know the sacred codes that reveal the nature of each obstacle on the path."

Authentication Errors

HTTP Code	Error	Description
`400`	`IP inválido ou ausente`	Client IP could not be validated
`401`	`Missing_'X-Bifrost-Invoke'_header`	Authentication header was not sent
`401`	`Invalid_or_expired_API_key`	Invalid, revoked or expired API Key
`401`	`user_not_authenticated`	User not authenticated
`403`	`IP não autorizado`	IP is not in API Key whitelist
`429`	`limit_exceeded_for_rune`	Request limit exceeded

Validation Errors

HTTP Code	Error	Description
`400`	`invalid_parameters`	Invalid or missing parameters
`400`	`max_payouts_exceeded`	Limit of 50 payouts per request exceeded
`400`	`missing_required_fields`	Required fields missing
`400`	`duplicate_reference_id`	reference_id already exists in database
`400`	`invalid_crypto_amount`	Invalid crypto value
`400`	`invalid_fiat_amount`	Invalid fiat value
`400`	`invalid_network`	Invalid or inactive blockchain network
`400`	`unsupported_token`	Token not supported or incompatible with network
`400`	`token_network_mismatch`	Token is not supported on specified network
`400`	`limit_exceeded`	Value outside min/max limits

Business Errors

HTTP Code	Error	Description
`400`	`insufficient_balance`	Insufficient balance
`400`	`price_unavailable`	Price unavailable for conversion
`404`	`user_not_found`	User not found
`404`	`record_not_found`	Record not found

System Errors

HTTP Code	Error	Description
`500`	`internal_error`	Internal server error
`500`	`database_transaction_failed`	Database transaction failed
`500`	`service_unavailable`	Service temporarily unavailable

Error Response Example

{
  "error": "insufficient_balance",
  "details": {
    "field": "crypto_amount",
    "current_balance": 45.50,
    "required_amount": 50.00
  }
}

Transaction Status

"In the eternal records of Valhalla, each transaction passes through three sacred states. Know the meaning of each step of the journey through the nine realms."

Payment Status (Payout)

⏱

pending

Awaiting processing

✓

completed

Transaction completed successfully

✗

failed

Transaction failed

Receipt Status (Payin)

⏱

pending

Awaiting payment

✓

completed

Payment received and confirmed

✗

failed

Expired or failed

Best Practices

"The wisdom of the elders teaches that following the right paths ensures a safe and prosperous journey through the nine digital realms."

Security

✓ Do

Store your API Key in environment variables
Configure IP Whitelist
Validate webhook signatures
Use HTTPS in all requests
Implement request timeouts

✗ Don't

Share API Key publicly
Commit API Keys to Git
Use the same API Key in multiple environments
Ignore webhook signature validation

Performance

Use cache when possible (summary endpoints have 5-minute cache)
Implement proper pagination
Avoid excessive requests (respect rate limit)
Process webhooks asynchronously

Idempotency

Use unique and meaningful reference_id
Before creating new transaction, check if reference_id already exists
Implement retry handling in webhooks

Complete Implementation Example

Complete PHP example of how to integrate with Bifrost API:

<?php

class BifrostClient
{
    private $apiKey;
    private $baseUrl = 'https://bridge.bifrostcrypto.com';
    
    public function __construct(string $apiKey)
    {
        $this->apiKey = $apiKey;
    }
    
    /**
     * Criar payout
     */
    public function createPayout(array $data): array
    {
        return $this->request('POST', '/external/payout', $data);
    }
    
    /**
     * Criar payin
     */
    public function createPayin(array $data): array
    {
        return $this->request('POST', '/external/payin', $data);
    }
    
    /**
     * Consultar saldos
     */
    public function getBalances(): array
    {
        return $this->request('GET', '/external/balances');
    }
    
    /**
     * Validar webhook
     */
    public function validateWebhook(
        string $payload, 
        string $signature, 
        string $ipnSecret
    ): bool {
        $calculatedSignature = hash_hmac('sha256', $payload, $ipnSecret);
        return hash_equals($calculatedSignature, $signature);
    }
    
    /**
     * Request genérico
     */
    private function request(
        string $method, 
        string $endpoint, 
        ?array $data = null
    ): array {
        $ch = curl_init();
        
        $headers = [
            'X-Bifrost-Invoke: ' . $this->apiKey,
            'Content-Type: application/json',
            'Accept: application/json'
        ];
        
        curl_setopt_array($ch, [
            CURLOPT_URL => $this->baseUrl . $endpoint,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 30,
            CURLOPT_HTTPHEADER => $headers,
            CURLOPT_CUSTOMREQUEST => $method,
        ]);
        
        if ($data && in_array($method, ['POST', 'PUT', 'PATCH'])) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        $result = json_decode($response, true);
        
        if ($httpCode >= 400) {
            throw new Exception($result['error'] ?? 'Request failed', $httpCode);
        }
        
        return $result;
    }
}

// Uso
$client = new BifrostClient('your_access_rune_to_the_bifrost');

// Criar payout
try {
    $result = $client->createPayout([
        'wallet' => '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
        'crypto_currency' => 'USDT',
        'process_by' => 'crypto_amount',
        'crypto_amount' => 50.00,
        'reference_id' => 'PAYOUT-' . uniqid(),
        'network' => 'BinanceSmartChain',
        'feetakenfromamount' => 1,
        'webhook_url' => 'https://suaapi.com/webhooks/payout'
    ]);
    
    echo "Payout criado: " . $result['results'][0]['internal_reference'];
    
} catch (Exception $e) {
    echo "Erro: " . $e->getMessage();
}

// Processar webhook
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_BIFROST_SIGNATURE'] ?? '';
$ipnSecret = getenv('BIFROST_IPN_SECRET');

if ($client->validateWebhook($payload, $signature, $ipnSecret)) {
    $data = json_decode($payload, true);
    
    // Processar webhook...
    http_response_code(200);
    echo json_encode(['status' => 'success']);
} else {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
}

The Nine Blockchain Realms

Warning from Asgard's Guardians

The Nine Realms and Their Mythical Correspondences

Bitcoin - Asgard

Ethereum - Midgard

Binance Smart Chain - Alfheim

Optimism - Ljosalfgard

Arbitrum - Vanaheim

Cronos - Jotunheim

Avalanche - Niflheim

Polygon - Svartalfheim

Base - Muspelheim

Coins of the Mortal Realms

Ancestral Warning from the Guardians

ARS - Pesos of the Argentine Realm

AUD - Dollars of the Australian Realm

BRL - Gold of the Brazilian Kingdom

CAD - Dollars of the Canadian Realm

CHF - Francs of the Swiss Realm

EUR - Coins of the European Realm

GBP - Pounds of the Britannia Realm

INR - Rupees of the Indian Realm

JPY - Yen of the Rising Sun Realm

MXN - Pesos of the Mexican Realm

THB - Bahts of the Thai Realm

USD - Silver of the American Empire

Heimdall's Seal

The Ancestral Access Rune

The Invocation Rune

Mystical Rune Example

Request Limits

Sacred Rules of Limits

Default Limit

🚫 When Limit is Exceeded

Global Realms Summary

Ancestral Warning from the Guardians

Treasures of Asgard

Balance Query

Statement Scrolls

Query with Filters

Scroll Invocation Runes

Temporal Navigation Runes

Mystical Filtering Runes

1. Direction of Cosmic Winds

2. Nature of Invoked Magic

3. Vaults of the Nine Realms

4. Temporal Portals

5. Energy Magnitude

6. Identification Seal

Query Example

Prices and Conversions

Query Parameters

Query Example

Conversion Examples

Query Example

Creating Divine Payments

Payment Example

Listing Payments

Query Example

Records Consultation Runes

Archive Navigation Runes

Payment Filtering Runes

1. Divine Forge State

2. Nine Realms Currency

3. Bridges Between Worlds

4. Temporal Portals

5. Mystical Identification Seal

Creating Receipts

Receipt Example

Listing Receipts

Query Example

Treasures Consultation Runes

Archive Navigation Runes

Deposits Filtering Runes

1. Ancestral Magic State

2. Nine Realms Currency

3. Bridges Between Worlds

4. Temporal Portals

5. Mystical Identification Seal

Complete Query Example