# Create a bridge order

> Create a native bridge order for one asset and direction (supply your own sessionId only with a valid integrator key)

`POST /v2/bridges`

Create a native bridge order for one asset and direction (supply your own sessionId only with a valid integrator key).

**Authentication:** None required. Optional: [integrator key](https://docs.wagyu.xyz/authentication.md) in `X-Integrator-Key`.

> **This creates a real order:** There is no sandbox and no idempotency key. Never retry this call automatically.

## Request body

Send one of these 2 shapes:

### Shape 1

- `toAddress` · string · **required** — Destination address. Its chain-specific validity is checked by the engine.
- `sessionId` · string (pattern `^[0-9a-f-]{16,64}$`) — Optional session credential for an integrator to group its own orders. Requires a valid integrator API key.
- `refundAddress` · string (max 256) — Refund destination. Its chain-specific validity is checked by the engine.
- `source` · object — Where the visit that created this order came from. Marketing only: stored apart from the order, counted in reports, never published back on any order read.
  - `utmSource` · string (pattern `^[a-z0-9._-]{1,64}$`) — The landing link's utm_source.
  - `utmMedium` · string (pattern `^[a-z0-9._-]{1,64}$`) — The landing link's utm_medium.
  - `utmCampaign` · string (pattern `^[a-z0-9._-]{1,64}$`) — The landing link's utm_campaign.
  - `referrer` · string (pattern `^(?=.{1,253}$)[a-z0-9-]{1,63}(?:\.[a-z0-9-]{1,63})+$`) — Hostname of the site the visitor came from. Never a full URL.
  - `landing` · string (pattern `^\/[A-Za-z0-9/._-]{0,199}$`) — Path of the visit's first page.
- `asset` · `"xmr"` · `"trx"` · `"zec"` · **required** — Registered native-bridge asset key, never a display symbol.
- `direction` · `"deposit"` · **required** — Mint the wrapped asset from a native-coin deposit.

### Shape 2: with `senderAddress`

- `toAddress` · string · **required** — Destination address. Its chain-specific validity is checked by the engine.
- `sessionId` · string (pattern `^[0-9a-f-]{16,64}$`) — Optional session credential for an integrator to group its own orders. Requires a valid integrator API key.
- `refundAddress` · string (max 256) — Refund destination. Its chain-specific validity is checked by the engine.
- `source` · object — Where the visit that created this order came from. Marketing only: stored apart from the order, counted in reports, never published back on any order read.
  - `utmSource` · string (pattern `^[a-z0-9._-]{1,64}$`) — The landing link's utm_source.
  - `utmMedium` · string (pattern `^[a-z0-9._-]{1,64}$`) — The landing link's utm_medium.
  - `utmCampaign` · string (pattern `^[a-z0-9._-]{1,64}$`) — The landing link's utm_campaign.
  - `referrer` · string (pattern `^(?=.{1,253}$)[a-z0-9-]{1,63}(?:\.[a-z0-9-]{1,63})+$`) — Hostname of the site the visitor came from. Never a full URL.
  - `landing` · string (pattern `^\/[A-Za-z0-9/._-]{0,199}$`) — Path of the visit's first page.
- `asset` · `"xmr"` · `"trx"` · `"zec"` · **required** — Registered native-bridge asset key, never a display symbol.
- `direction` · `"withdraw"` · **required** — Return the native coin against the wrapped asset.
- `senderAddress` · string or null — Intake hint only: the Hyperliquid address you intend to return the wrapped asset from. Fees and any pause bypass are bound to the sender the workflow actually verifies on-chain.

## Response

`200` returns an object with:

- **product = "bridge"**
  - `orderId` · string · **required**
  - `product` · `"bridge"` · **required**
  - `sessionId` · string (pattern `^[0-9a-f-]{16,64}$`) · **required** — 16–64 character hexadecimal/hyphen owner-session credential.
  - `asset` · `"xmr"` · `"trx"` · `"zec"` · **required** — Registered native-bridge asset key, never a display symbol.
  - `status` · `"awaiting_deposit"` · `"awaiting_xmr1"` · `"awaiting_trx1"` · `"awaiting_zec1"` · `"processing"` · `"completed"` · `"failed"` · `"expired"` · `"refunded"` · `"needs_review"` · **required**
  - `customerState` · one of the variants below · **required** — Authoritative customer display/action state. Clients must not infer lifecycle from status or resource presence.
    - _Nested fields: see `openapi.json`._
  - `destination` · string · **required**
  - `expiresAt` · string · **required**
  - `direction` · `"deposit"` · **required**
  - `depositAddress` · string · **required**
  - `depositAddressForms` · array of object
    - _Nested fields: see `openapi.json`._
- **product = "bridge"**
  - `orderId` · string · **required**
  - `product` · `"bridge"` · **required**
  - `sessionId` · string (pattern `^[0-9a-f-]{16,64}$`) · **required** — 16–64 character hexadecimal/hyphen owner-session credential.
  - `asset` · `"xmr"` · `"trx"` · `"zec"` · **required** — Registered native-bridge asset key, never a display symbol.
  - `status` · `"awaiting_deposit"` · `"awaiting_xmr1"` · `"awaiting_trx1"` · `"awaiting_zec1"` · `"processing"` · `"completed"` · `"failed"` · `"expired"` · `"refunded"` · `"needs_review"` · **required**
  - `customerState` · one of the variants below · **required** — Authoritative customer display/action state. Clients must not infer lifecycle from status or resource presence.
    - _Nested fields: see `openapi.json`._
  - `destination` · string · **required**
  - `expiresAt` · string · **required**
  - `direction` · `"withdraw"` · **required**
  - `xmr1DepositAddress` · string or null · **required**

Errors use the [standard error envelope](https://docs.wagyu.xyz/actions-and-retries.md#the-error-envelope): branch on `code`, never on the message.

## Example

<!-- curl -->
```bash
curl -X POST 'https://api-beta.wagyu.xyz/v2/bridges' \
  -H 'content-type: application/json' \
  -d '{
    "asset": "xmr",
    "direction": "deposit",
    "toAddress": "<your-hyperliquid-address>"
  }'
```

<!-- JavaScript -->
```javascript
const res = await fetch('https://api-beta.wagyu.xyz/v2/bridges', {
  method: 'POST',
  headers: {"content-type":"application/json"},
  body: JSON.stringify({
    "asset": "xmr",
    "direction": "deposit",
    "toAddress": "<your-hyperliquid-address>"
  }),
});
const data = await res.json();
```

<!-- Python -->
```python
import requests

res = requests.post('https://api-beta.wagyu.xyz/v2/bridges', json={
        "asset": "xmr",
        "direction": "deposit",
        "toAddress": "<your-hyperliquid-address>"
    }, timeout=30)
data = res.json()
```

_No response is captured for this route: calling it creates or changes a real order. The response fields above come from the live contract._

---
Source: https://docs.wagyu.xyz/api-reference/create-bridge-order · Built from the live Wagyu API on 2026-11-04.