Create a bridge
Moves your network liquidity of a token from one network to another, so that payouts on the destination network have enough to draw on. The move is instant. Your API account balance for the token goes down by the fee only.
How it works
A payout draws on two balances: the API account for its token, and your network liquidity for that token on the network you pay out on. A bridge changes the second one:
| Balance | Change |
|---|---|
Network liquidity on fromNetwork | Goes down by amount plus fee |
Network liquidity on toNetwork | Goes up by amount |
API account balance for token | Goes down by fee |
Knit refuses the bridge, and changes nothing, if the API account balance or
the liquidity on fromNetwork is less than amount plus fee. Call
Quote a bridge first to see the fee.
If your business keeps deposits on Tron in its own Tron wallet, that part of your Tron liquidity pays your Tron payouts and cannot be moved. Only the rest of your Tron liquidity can be bridged.
Body
Your own reference for this bridge. It must be unique among the bridges of your business. Maximum 255 characters. This is what makes retries safe.
USDT or USDC. Coins cannot be moved between networks.
The network to move the liquidity from, for example TRON_MAINNET. It must
be a network that GET /api/v1/networks
shows the token on.
The network to move the liquidity to, for example ETHEREUM_MAINNET. Payouts
of the token must be active on it in GET /api/v1/networks. It must not be
the same as fromNetwork.
The amount that arrives on toNetwork, in token units. Minimum 0.01. The
fee is added on top.
Reusing a reference
Knit checks merchantReference first. A request with a reference that your
business has already used gets the duplicate 400 shown under
Errors, and nothing moves. This is also true for a retry that
arrives while the first request is still being processed.
If you are not sure of the outcome, send the request again with the same
reference and the same body, or look the reference up with
List bridges and ?merchantReference=.
Request
curl -X POST "https://api-prod.useknit.io/api/v1/bridges" \
-H "Authorization: Bearer $KNIT_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"merchantReference": "rebalance-001",
"token": "USDT",
"fromNetwork": "TRON_MAINNET",
"toNetwork": "ETHEREUM_MAINNET",
"amount": "200"
}'Response
Returns 201. The bridge is complete when you get the response: its status is
SUCCESSFUL.
{
"statusCode": 201,
"message": "Bridge created successfully",
"data": {
"id": "9f3c2a71-5d0e-4b8a-9a43-6c2f1e7b8d10",
"merchantReference": "rebalance-001",
"token": "USDT",
"fromNetwork": "TRON_MAINNET",
"toNetwork": "ETHEREUM_MAINNET",
"amount": "200",
"fee": "2",
"totalDebit": "202",
"accountBalanceBefore": "500",
"accountBalanceAfter": "498",
"status": "SUCCESSFUL",
"createdAt": "2026-11-21T23:10:04.000000Z"
},
"success": true
}The amount added to your liquidity on toNetwork.
The bridge fee. 0 when no fee applies.
amount plus fee: the amount taken from your liquidity on fromNetwork.
The API account balance for token before the bridge.
The API account balance for token after the bridge. It is lower than
accountBalanceBefore by fee only.
Always SUCCESSFUL. A bridge that Knit refuses is not created.
When the fee is above 0, the statement of the
API account shows one DEBIT entry for the fee, with category and
sourceType BRIDGE and sourceId the bridge id. A bridge with no fee
does not change the balance and has no entry.
Errors
| Status | Cause |
|---|---|
400 | A field failed validation, for example a merchantReference your business has already used, a coin as token, the same network twice, or a network the token cannot be moved from or to |
400 | Insufficient balance in wallet: the API account balance is less than amount plus fee |
400 | Insufficient network liquidity: the liquidity on fromNetwork is less than amount plus fee |
400 | Only 200 USDT, including the bridge fee, can be moved from TRON_MAINNET. …: part of the liquidity is held in your business's own wallet on that network, and the rest is less than amount plus fee |
401 | Missing or invalid token, IP not allow-listed, or missing payout-wallets:write |
403 | API Services are not enabled for your business |
404 | Wallet not found for the specified token: no API account exists for that token yet |
503 | Bridges are temporarily unavailable. Please try again later. Knit has paused bridges. Nothing moved, so try again later with the same reference |
A validation failure names the field in errors. A reused merchantReference
is always the message, even when another field also fails:
{
"message": "The merchant reference has already been taken.",
"errors": {
"merchantReference": ["The merchant reference has already been taken."]
}
}A network that a token cannot be moved from:
{
"message": "USDC can't be moved from TRON_MAINNET.",
"errors": {
"fromNetwork": ["USDC can't be moved from TRON_MAINNET."]
}
}A refused bridge carries the standard envelope and no errors:
{
"statusCode": 400,
"message": "Insufficient network liquidity",
"data": null,
"success": false
}