Create connection

curl --request POST \
  --url https://dev.bringin.xyz/api/v0/bringin-link \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "type": "<string>",
  "subtype": "<string>",
  "destinationAddress": "<string>",
  "destinationCurrency": "<string>",
  "network": "<string>",
  "sourceCurrency": "<string>",
  "beneficiary": {
    "beneficiary.iban": "<string>",
    "beneficiary.bic": "<string>",
    "beneficiary.name": "<string>"
  },
  "beneficiaryId": "<string>",
  "lnAddress": "<string>",
  "whitelistedAddressId": "<string>"
}
'

import requests

url = "https://dev.bringin.xyz/api/v0/bringin-link"

payload = {
    "name": "<string>",
    "type": "<string>",
    "subtype": "<string>",
    "destinationAddress": "<string>",
    "destinationCurrency": "<string>",
    "network": "<string>",
    "sourceCurrency": "<string>",
    "beneficiary": {
        "beneficiary.iban": "<string>",
        "beneficiary.bic": "<string>",
        "beneficiary.name": "<string>"
    },
    "beneficiaryId": "<string>",
    "lnAddress": "<string>",
    "whitelistedAddressId": "<string>"
}
headers = {
    "api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    type: '<string>',
    subtype: '<string>',
    destinationAddress: '<string>',
    destinationCurrency: '<string>',
    network: '<string>',
    sourceCurrency: '<string>',
    beneficiary: {
      'beneficiary.iban': '<string>',
      'beneficiary.bic': '<string>',
      'beneficiary.name': '<string>'
    },
    beneficiaryId: '<string>',
    lnAddress: '<string>',
    whitelistedAddressId: '<string>'
  })
};

fetch('https://dev.bringin.xyz/api/v0/bringin-link', 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://dev.bringin.xyz/api/v0/bringin-link",
  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([
    'name' => '<string>',
    'type' => '<string>',
    'subtype' => '<string>',
    'destinationAddress' => '<string>',
    'destinationCurrency' => '<string>',
    'network' => '<string>',
    'sourceCurrency' => '<string>',
    'beneficiary' => [
        'beneficiary.iban' => '<string>',
        'beneficiary.bic' => '<string>',
        'beneficiary.name' => '<string>'
    ],
    'beneficiaryId' => '<string>',
    'lnAddress' => '<string>',
    'whitelistedAddressId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api-key: <api-key>"
  ],
]);

$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://dev.bringin.xyz/api/v0/bringin-link"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"type\": \"<string>\",\n  \"subtype\": \"<string>\",\n  \"destinationAddress\": \"<string>\",\n  \"destinationCurrency\": \"<string>\",\n  \"network\": \"<string>\",\n  \"sourceCurrency\": \"<string>\",\n  \"beneficiary\": {\n    \"beneficiary.iban\": \"<string>\",\n    \"beneficiary.bic\": \"<string>\",\n    \"beneficiary.name\": \"<string>\"\n  },\n  \"beneficiaryId\": \"<string>\",\n  \"lnAddress\": \"<string>\",\n  \"whitelistedAddressId\": \"<string>\"\n}")

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

	req.Header.Add("api-key", "<api-key>")
	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://dev.bringin.xyz/api/v0/bringin-link")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"type\": \"<string>\",\n  \"subtype\": \"<string>\",\n  \"destinationAddress\": \"<string>\",\n  \"destinationCurrency\": \"<string>\",\n  \"network\": \"<string>\",\n  \"sourceCurrency\": \"<string>\",\n  \"beneficiary\": {\n    \"beneficiary.iban\": \"<string>\",\n    \"beneficiary.bic\": \"<string>\",\n    \"beneficiary.name\": \"<string>\"\n  },\n  \"beneficiaryId\": \"<string>\",\n  \"lnAddress\": \"<string>\",\n  \"whitelistedAddressId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://dev.bringin.xyz/api/v0/bringin-link")

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

request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"type\": \"<string>\",\n  \"subtype\": \"<string>\",\n  \"destinationAddress\": \"<string>\",\n  \"destinationCurrency\": \"<string>\",\n  \"network\": \"<string>\",\n  \"sourceCurrency\": \"<string>\",\n  \"beneficiary\": {\n    \"beneficiary.iban\": \"<string>\",\n    \"beneficiary.bic\": \"<string>\",\n    \"beneficiary.name\": \"<string>\"\n  },\n  \"beneficiaryId\": \"<string>\",\n  \"lnAddress\": \"<string>\",\n  \"whitelistedAddressId\": \"<string>\"\n}"

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

{
  "bringinLink": {
    "id": "a8558b90-6a87-4c81-a767-9725d5a23a45",
    "name": "Blue Wallet",
    "type": "FIAT_TO_CRYPTO",
    "subtype": "ONCHAIN",
    "status": "INITIATING",
    "createdAt": "2026-03-24T08:31:53.143Z",
    "updatedAt": "2026-03-24T08:31:53.143Z"
  }
}

POST

api

bringin-link

Create connection

curl --request POST \
  --url https://dev.bringin.xyz/api/v0/bringin-link \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "type": "<string>",
  "subtype": "<string>",
  "destinationAddress": "<string>",
  "destinationCurrency": "<string>",
  "network": "<string>",
  "sourceCurrency": "<string>",
  "beneficiary": {
    "beneficiary.iban": "<string>",
    "beneficiary.bic": "<string>",
    "beneficiary.name": "<string>"
  },
  "beneficiaryId": "<string>",
  "lnAddress": "<string>",
  "whitelistedAddressId": "<string>"
}
'

import requests

url = "https://dev.bringin.xyz/api/v0/bringin-link"

payload = {
    "name": "<string>",
    "type": "<string>",
    "subtype": "<string>",
    "destinationAddress": "<string>",
    "destinationCurrency": "<string>",
    "network": "<string>",
    "sourceCurrency": "<string>",
    "beneficiary": {
        "beneficiary.iban": "<string>",
        "beneficiary.bic": "<string>",
        "beneficiary.name": "<string>"
    },
    "beneficiaryId": "<string>",
    "lnAddress": "<string>",
    "whitelistedAddressId": "<string>"
}
headers = {
    "api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    type: '<string>',
    subtype: '<string>',
    destinationAddress: '<string>',
    destinationCurrency: '<string>',
    network: '<string>',
    sourceCurrency: '<string>',
    beneficiary: {
      'beneficiary.iban': '<string>',
      'beneficiary.bic': '<string>',
      'beneficiary.name': '<string>'
    },
    beneficiaryId: '<string>',
    lnAddress: '<string>',
    whitelistedAddressId: '<string>'
  })
};

fetch('https://dev.bringin.xyz/api/v0/bringin-link', 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://dev.bringin.xyz/api/v0/bringin-link",
  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([
    'name' => '<string>',
    'type' => '<string>',
    'subtype' => '<string>',
    'destinationAddress' => '<string>',
    'destinationCurrency' => '<string>',
    'network' => '<string>',
    'sourceCurrency' => '<string>',
    'beneficiary' => [
        'beneficiary.iban' => '<string>',
        'beneficiary.bic' => '<string>',
        'beneficiary.name' => '<string>'
    ],
    'beneficiaryId' => '<string>',
    'lnAddress' => '<string>',
    'whitelistedAddressId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api-key: <api-key>"
  ],
]);

$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://dev.bringin.xyz/api/v0/bringin-link"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"type\": \"<string>\",\n  \"subtype\": \"<string>\",\n  \"destinationAddress\": \"<string>\",\n  \"destinationCurrency\": \"<string>\",\n  \"network\": \"<string>\",\n  \"sourceCurrency\": \"<string>\",\n  \"beneficiary\": {\n    \"beneficiary.iban\": \"<string>\",\n    \"beneficiary.bic\": \"<string>\",\n    \"beneficiary.name\": \"<string>\"\n  },\n  \"beneficiaryId\": \"<string>\",\n  \"lnAddress\": \"<string>\",\n  \"whitelistedAddressId\": \"<string>\"\n}")

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

	req.Header.Add("api-key", "<api-key>")
	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://dev.bringin.xyz/api/v0/bringin-link")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"type\": \"<string>\",\n  \"subtype\": \"<string>\",\n  \"destinationAddress\": \"<string>\",\n  \"destinationCurrency\": \"<string>\",\n  \"network\": \"<string>\",\n  \"sourceCurrency\": \"<string>\",\n  \"beneficiary\": {\n    \"beneficiary.iban\": \"<string>\",\n    \"beneficiary.bic\": \"<string>\",\n    \"beneficiary.name\": \"<string>\"\n  },\n  \"beneficiaryId\": \"<string>\",\n  \"lnAddress\": \"<string>\",\n  \"whitelistedAddressId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://dev.bringin.xyz/api/v0/bringin-link")

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

request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"type\": \"<string>\",\n  \"subtype\": \"<string>\",\n  \"destinationAddress\": \"<string>\",\n  \"destinationCurrency\": \"<string>\",\n  \"network\": \"<string>\",\n  \"sourceCurrency\": \"<string>\",\n  \"beneficiary\": {\n    \"beneficiary.iban\": \"<string>\",\n    \"beneficiary.bic\": \"<string>\",\n    \"beneficiary.name\": \"<string>\"\n  },\n  \"beneficiaryId\": \"<string>\",\n  \"lnAddress\": \"<string>\",\n  \"whitelistedAddressId\": \"<string>\"\n}"

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

{
  "bringinLink": {
    "id": "a8558b90-6a87-4c81-a767-9725d5a23a45",
    "name": "Blue Wallet",
    "type": "FIAT_TO_CRYPTO",
    "subtype": "ONCHAIN",
    "status": "INITIATING",
    "createdAt": "2026-03-24T08:31:53.143Z",
    "updatedAt": "2026-03-24T08:31:53.143Z"
  }
}

Create a new connection (BringinLink). Returns immediately with INITIATING status (HTTP 202). The standing order is created asynchronously — poll GET /bringin-link/{id} every 2-3 seconds to track progress. Requires a per-user api-key.

Always call GET /bringin-link first to check for existing connections. Creating a duplicate returns a 409 error. See best practices.

name

string

required

User-facing label (2-50 chars). Must be unique per user across active connections.

type

string

required

FIAT_TO_CRYPTO or CRYPTO_TO_FIAT

subtype

string

required

ONCHAIN or LN (Lightning is only supported for CRYPTO_TO_FIAT)

destinationAddress

string

Crypto address (26-90 chars). Required for FIAT_TO_CRYPTO unless whitelistedAddressId is provided.

destinationCurrency

string

default:"BTC"

Target crypto: BTC, ETH, USDC, USDT, or POL. For FIAT_TO_CRYPTO only.

network

string

Blockchain network. Required for FIAT_TO_CRYPTO. Must be compatible with destinationCurrency:

BTC: BTC
ETH: ETH
USDC: USDC (Ethereum) or POLYGON
USDT: USDT (Polygon) or ETH (Ethereum)
POL: POL or POLYGON

sourceCurrency

string

default:"BTC"

Source crypto for CRYPTO_TO_FIAT + ONCHAIN. Options: BTC, ETH, USDC.

beneficiary

object

Bank account details. Required for CRYPTO_TO_FIAT unless beneficiaryId is provided.

Show properties

beneficiary.iban

string

required

Valid IBAN (normalized to uppercase)

beneficiary.bic

string

required

BIC/SWIFT code (normalized to uppercase)

beneficiary.name

string

required

Account holder name (2-100 chars)

beneficiaryId

string

UUID of an existing beneficiary. Use instead of beneficiary object. The IBAN is auto-whitelisted if needed.

lnAddress

string

Lightning address username (3-30 chars, lowercase alphanumeric + _/-, no consecutive specials). Required for LN subtype. Becomes {username}@bringin.xyz.

whitelistedAddressId

string

Use an existing whitelisted address instead of destinationAddress.

{
  "bringinLink": {
    "id": "a8558b90-6a87-4c81-a767-9725d5a23a45",
    "name": "Blue Wallet",
    "type": "FIAT_TO_CRYPTO",
    "subtype": "ONCHAIN",
    "status": "INITIATING",
    "createdAt": "2026-03-24T08:31:53.143Z",
    "updatedAt": "2026-03-24T08:31:53.143Z"
  }
}

After creation

Poll GET /bringin-link/{id} every 2-3 seconds. Typical processing time is 5-15 seconds.

Status	Action
`INITIATING`	Keep polling
`PENDING`	Show OTP screen — use `challengeId` to confirm
`ACTIVE`	Connection is ready (standing order was reused, no OTP needed)
`FAILED`	Show user-friendly error, direct to support@bringin.xyz

If still INITIATING after 60 seconds, show a timeout message.

Idempotent behaviors

These happen automatically — no client action needed:

Existing beneficiary — If the IBAN already exists for this user, the existing beneficiary is reused
Existing whitelisted address — If the crypto address is already whitelisted on the same network, it’s reused
Standing order reuse (LN only) — If a standing order exists for the same beneficiary, a new LN address points to the existing one

Get onboarding status Get connection

​After creation

​Idempotent behaviors

After creation

Idempotent behaviors