> ## 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 connection

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**.

<Warning>Always call `GET /bringin-link` first to check for existing connections. Creating a duplicate returns a `409` error. See [best practices](/guides/connection-integration#best-practices).</Warning>

<ParamField body="name" type="string" required>
  User-facing label (2-50 chars). Must be unique per user across active connections.
</ParamField>

<ParamField body="type" type="string" required>
  `FIAT_TO_CRYPTO` or `CRYPTO_TO_FIAT`
</ParamField>

<ParamField body="subtype" type="string" required>
  `ONCHAIN` or `LN` (Lightning is only supported for `CRYPTO_TO_FIAT`)
</ParamField>

<ParamField body="destinationAddress" type="string">
  Crypto address (26-90 chars). Required for `FIAT_TO_CRYPTO` unless `whitelistedAddressId` is provided.
</ParamField>

<ParamField body="destinationCurrency" type="string" default="BTC">
  Target crypto: `BTC`, `ETH`, `USDC`, `USDT`, or `POL`. For `FIAT_TO_CRYPTO` only.
</ParamField>

<ParamField body="network" type="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`
</ParamField>

<ParamField body="sourceCurrency" type="string" default="BTC">
  Source crypto for `CRYPTO_TO_FIAT` + `ONCHAIN`. Options: `BTC`, `ETH`, `USDC`.
</ParamField>

<ParamField body="beneficiary" type="object">
  Bank account details. Required for `CRYPTO_TO_FIAT` unless `beneficiaryId` is provided.

  <Expandable title="properties">
    <ParamField body="beneficiary.iban" type="string" required>
      Valid IBAN (normalized to uppercase)
    </ParamField>

    <ParamField body="beneficiary.bic" type="string" required>
      BIC/SWIFT code (normalized to uppercase)
    </ParamField>

    <ParamField body="beneficiary.name" type="string" required>
      Account holder name (2-100 chars)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="beneficiaryId" type="string">
  UUID of an existing beneficiary. Use instead of `beneficiary` object. The IBAN is auto-whitelisted if needed.
</ParamField>

<ParamField body="lnAddress" type="string">
  Lightning address username (3-30 chars, lowercase alphanumeric + `_`/`-`, no consecutive specials). Required for `LN` subtype. Becomes `{username}@bringin.xyz`.
</ParamField>

<ParamField body="whitelistedAddressId" type="string">
  Use an existing whitelisted address instead of `destinationAddress`.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

### 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](mailto:support@bringin.xyz) |

<Note>If still `INITIATING` after 60 seconds, show a timeout message.</Note>

### 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