Onchain Actions

private/register_bridge_deposit

Reports a Li.Fi bridge into one of the caller’s deposit addresses the moment its source transaction is sent, so public/get_pending_deposits shows it as bridging at once with the quoted amount, before Li.Fi indexes it. Takes the source chain and transaction, the quote’s transactionId, the deposit address, the source and delivered tokens and the quoted toAmount. Idempotent per source transaction. Display only: nothing is credited from it, and a registration Li.Fi never confirms expires.

POST

private

register_bridge_deposit

curl --request POST \
  --url https://api.derive.xyz/v3/private/register_bridge_deposit \
  --header 'Content-Type: application/json' \
  --data '
{
  "bridge_token": "<string>",
  "bridge_token_decimals": 1,
  "deposit_address": "<string>",
  "expected_amount": "<string>",
  "rail": "<string>",
  "source_chain_id": 1,
  "source_token": "<string>",
  "source_tx_hash": "<string>",
  "wallet": "<string>",
  "provider_transfer_id": null,
  "tool": null
}
'

import requests

url = "https://api.derive.xyz/v3/private/register_bridge_deposit"

payload = {
    "bridge_token": "<string>",
    "bridge_token_decimals": 1,
    "deposit_address": "<string>",
    "expected_amount": "<string>",
    "rail": "<string>",
    "source_chain_id": 1,
    "source_token": "<string>",
    "source_tx_hash": "<string>",
    "wallet": "<string>",
    "provider_transfer_id": None,
    "tool": None
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    bridge_token: '<string>',
    bridge_token_decimals: 1,
    deposit_address: '<string>',
    expected_amount: '<string>',
    rail: '<string>',
    source_chain_id: 1,
    source_token: '<string>',
    source_tx_hash: '<string>',
    wallet: '<string>',
    provider_transfer_id: null,
    tool: null
  })
};

fetch('https://api.derive.xyz/v3/private/register_bridge_deposit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.derive.xyz/v3/private/register_bridge_deposit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'bridge_token' => '<string>',
    'bridge_token_decimals' => 1,
    'deposit_address' => '<string>',
    'expected_amount' => '<string>',
    'rail' => '<string>',
    'source_chain_id' => 1,
    'source_token' => '<string>',
    'source_tx_hash' => '<string>',
    'wallet' => '<string>',
    'provider_transfer_id' => null,
    'tool' => null
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.derive.xyz/v3/private/register_bridge_deposit"

	payload := strings.NewReader("{\n  \"bridge_token\": \"<string>\",\n  \"bridge_token_decimals\": 1,\n  \"deposit_address\": \"<string>\",\n  \"expected_amount\": \"<string>\",\n  \"rail\": \"<string>\",\n  \"source_chain_id\": 1,\n  \"source_token\": \"<string>\",\n  \"source_tx_hash\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"provider_transfer_id\": null,\n  \"tool\": null\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.derive.xyz/v3/private/register_bridge_deposit")
  .header("Content-Type", "application/json")
  .body("{\n  \"bridge_token\": \"<string>\",\n  \"bridge_token_decimals\": 1,\n  \"deposit_address\": \"<string>\",\n  \"expected_amount\": \"<string>\",\n  \"rail\": \"<string>\",\n  \"source_chain_id\": 1,\n  \"source_token\": \"<string>\",\n  \"source_tx_hash\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"provider_transfer_id\": null,\n  \"tool\": null\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.derive.xyz/v3/private/register_bridge_deposit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"bridge_token\": \"<string>\",\n  \"bridge_token_decimals\": 1,\n  \"deposit_address\": \"<string>\",\n  \"expected_amount\": \"<string>\",\n  \"rail\": \"<string>\",\n  \"source_chain_id\": 1,\n  \"source_token\": \"<string>\",\n  \"source_tx_hash\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"provider_transfer_id\": null,\n  \"tool\": null\n}"

response = http.request(request)
puts response.read_body

{
  "bridge_id": "<string>",
  "bridge_status": "<string>",
  "deposit_address": "<string>",
  "expected_amount": "<string>",
  "expires_at_ms": 123,
  "rail": "<string>",
  "source_chain_id": 1,
  "source_tx_hash": "<string>",
  "substatus": "<string>",
  "token": "<string>",
  "delivered_at_ms": 123,
  "provider_transfer_id": "<string>",
  "receiving_amount": "<string>",
  "receiving_token": "<string>",
  "receiving_tx_hash": "<string>",
  "source_address": "<string>"
}

Body

application/json

What the client sent and was quoted.

bridge_token

string

required

The ERC20 the bridge delivers on the destination chain.

bridge_token_decimals

integer<uint8>

required

bridge_token's decimals.

Required range: x >= 0

deposit_address

string

required

One of the wallet's escrows, from public/register_deposit_address.

expected_amount

string

required

What the quote says will arrive, in bridge_token's native units, as a decimal string (Li.Fi: estimate.toAmount).

rail

string

required

Bridge protocol: lifi. (layerzero is not registrable yet.)

source_chain_id

integer<uint64>

required

Chain the bridge was sent from.

Required range: x >= 0

source_token

string

required

The ERC20 sent on the source chain.

source_tx_hash

string

required

The bridge transaction on that chain.

wallet

string

required

The session's wallet.

provider_transfer_id

string | null

The provider's own id for the transfer, kept if the source transaction is sped up or replaced: Li.Fi's quote transactionId.

tool

string | null

The route the provider chose (Li.Fi: the quote's tool). Internal only.

Response

Success

Where a deposit came from. Named apart from DepositBridgeOrigin because schemars shares one namespace and would emit an order-dependent BridgeOrigin2.

bridge_id

string

required

Unique with rail; changes if a registered source tx is replaced, so key on provider_transfer_id when present.

bridge_status

string

required

registered (reported by the client, not yet confirmed by Li.Fi) submitted (in flight) delivered (landed on the destination chain) matched (joined to the L1 deposit) failed (the bridge refunded or could not fill — nothing reached the escrow) expired (unresolved past expires_at_ms; check the source chain) unmatched (delivered, but not credited within 24h; contact support)

deposit_address

string

required

The escrow the bridge delivers to.

expected_amount

string

required

Quoted amount expected to land, in token units (estimated until quoted); receiving_amount once delivered.

expires_at_ms

integer<int64>

required

When a still-registered or submitted bridge will be marked expired.

rail

string

required

Bridge protocol: lifi or layerzero.

source_chain_id

integer<uint64>

required

Chain the user sent from.

Required range: x >= 0

source_tx_hash

string

required

Their transaction on that chain.

substatus

string

required

The rail's detail, or TOKEN_MISMATCH when the escrow cannot credit the token.

token

string

required

The ERC20 expected to land in the escrow.

delivered_at_ms

integer<int64> | null

provider_transfer_id

string | null

The provider's own id for the bridge (Li.Fi: the quote's transactionId), stable through its lifecycle.

receiving_amount

string | null

What actually arrived, native units, as a decimal string.

receiving_token

string | null

receiving_tx_hash

string | null

The bridge's delivery transaction on the destination chain.

source_address

string | null

Their wallet on that chain, lower-cased; absent when the rail gave none.

private/register_bridge_deposit

curl --request POST \
  --url https://api.derive.xyz/v3/private/register_bridge_deposit \
  --header 'Content-Type: application/json' \
  --data '
{
  "bridge_token": "<string>",
  "bridge_token_decimals": 1,
  "deposit_address": "<string>",
  "expected_amount": "<string>",
  "rail": "<string>",
  "source_chain_id": 1,
  "source_token": "<string>",
  "source_tx_hash": "<string>",
  "wallet": "<string>",
  "provider_transfer_id": null,
  "tool": null
}
'

import requests

url = "https://api.derive.xyz/v3/private/register_bridge_deposit"

payload = {
    "bridge_token": "<string>",
    "bridge_token_decimals": 1,
    "deposit_address": "<string>",
    "expected_amount": "<string>",
    "rail": "<string>",
    "source_chain_id": 1,
    "source_token": "<string>",
    "source_tx_hash": "<string>",
    "wallet": "<string>",
    "provider_transfer_id": None,
    "tool": None
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    bridge_token: '<string>',
    bridge_token_decimals: 1,
    deposit_address: '<string>',
    expected_amount: '<string>',
    rail: '<string>',
    source_chain_id: 1,
    source_token: '<string>',
    source_tx_hash: '<string>',
    wallet: '<string>',
    provider_transfer_id: null,
    tool: null
  })
};

fetch('https://api.derive.xyz/v3/private/register_bridge_deposit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.derive.xyz/v3/private/register_bridge_deposit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'bridge_token' => '<string>',
    'bridge_token_decimals' => 1,
    'deposit_address' => '<string>',
    'expected_amount' => '<string>',
    'rail' => '<string>',
    'source_chain_id' => 1,
    'source_token' => '<string>',
    'source_tx_hash' => '<string>',
    'wallet' => '<string>',
    'provider_transfer_id' => null,
    'tool' => null
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.derive.xyz/v3/private/register_bridge_deposit"

	payload := strings.NewReader("{\n  \"bridge_token\": \"<string>\",\n  \"bridge_token_decimals\": 1,\n  \"deposit_address\": \"<string>\",\n  \"expected_amount\": \"<string>\",\n  \"rail\": \"<string>\",\n  \"source_chain_id\": 1,\n  \"source_token\": \"<string>\",\n  \"source_tx_hash\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"provider_transfer_id\": null,\n  \"tool\": null\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.derive.xyz/v3/private/register_bridge_deposit")
  .header("Content-Type", "application/json")
  .body("{\n  \"bridge_token\": \"<string>\",\n  \"bridge_token_decimals\": 1,\n  \"deposit_address\": \"<string>\",\n  \"expected_amount\": \"<string>\",\n  \"rail\": \"<string>\",\n  \"source_chain_id\": 1,\n  \"source_token\": \"<string>\",\n  \"source_tx_hash\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"provider_transfer_id\": null,\n  \"tool\": null\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.derive.xyz/v3/private/register_bridge_deposit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"bridge_token\": \"<string>\",\n  \"bridge_token_decimals\": 1,\n  \"deposit_address\": \"<string>\",\n  \"expected_amount\": \"<string>\",\n  \"rail\": \"<string>\",\n  \"source_chain_id\": 1,\n  \"source_token\": \"<string>\",\n  \"source_tx_hash\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"provider_transfer_id\": null,\n  \"tool\": null\n}"

response = http.request(request)
puts response.read_body

{
  "bridge_id": "<string>",
  "bridge_status": "<string>",
  "deposit_address": "<string>",
  "expected_amount": "<string>",
  "expires_at_ms": 123,
  "rail": "<string>",
  "source_chain_id": 1,
  "source_tx_hash": "<string>",
  "substatus": "<string>",
  "token": "<string>",
  "delivered_at_ms": 123,
  "provider_transfer_id": "<string>",
  "receiving_amount": "<string>",
  "receiving_token": "<string>",
  "receiving_tx_hash": "<string>",
  "source_address": "<string>"
}

HTTP & WS Methods

WS-only Methods

WS Subscriptions

private/register_bridge_deposit

Body

Response