Skip to main content
POST
/
api
/
v0
/
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>"
}
'
{
  "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"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.bringin.app/llms.txt

Use this file to discover all available pages before exploring further.

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.
​
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.
StatusAction
INITIATINGKeep polling
PENDINGShow OTP screen — use challengeId to confirm
ACTIVEConnection is ready (standing order was reused, no OTP needed)
FAILEDShow 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