> ## Documentation Index
> Fetch the complete documentation index at: https://docs.1tx.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Transactions API

> Build buy and sell calldata bundles for direct wallet execution

## Overview

The Transactions API is the execution-facing part of the 1tx backend.

Use it when you want 1tx to:

* choose the best source chain for a deposit,
* calculate quotes and slippage-protected minimum outputs,
* and return the exact calldata bundle your user should sign.

The current flow is **stateless**:

1. Call `POST /transactions/buy` or `POST /transactions/sell`.
2. Present the returned transaction bundle to the user wallet.
3. Send the transactions in order.
4. For cross-chain buys, monitor the bridge via the CCTP API using the source transaction hash.

<Note>
  Transaction build endpoints require both a bearer token and an API key. Discovery endpoints such as `/instruments`, `/chains`, and `/quotes` only require an API key.
</Note>

## Build Buy Transaction

<span style={{color: '#EAB308', fontWeight: 'bold'}}>POST</span> `/transactions/buy`

Build a transaction bundle that calls router `buy()` for a 1tx instrument.

The backend will:

* validate the instrument,
* auto-select a source chain unless `sourceChainId` is provided,
* quote the deposit on the destination chain,
* add an approval transaction only when needed,
* and return the calldata bundle to execute.

### Request Body

| Field            | Type   | Required | Description                                                                                      |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `userAddress`    | string | Yes      | Wallet address that will sign the transactions                                                   |
| `instrumentId`   | string | Yes      | Target instrument ID                                                                             |
| `amountUsdc`     | string | Yes      | Deposit amount in human-readable USDC, e.g. `"1000.50"`                                          |
| `sourceChainId`  | number | No       | Force a specific source chain instead of auto-selecting from balances                            |
| `slippageBps`    | number | No       | Slippage tolerance in basis points. Defaults to `50`                                             |
| `referralFeeBps` | number | No       | Referral fee in basis points (0–500, i.e. up to 5%). Defaults to `0`. Requires `referralWallet`. |
| `referralWallet` | string | No       | Address that receives the referral fee. Required when `referralFeeBps > 0`.                      |

```bash theme={null}
curl -X POST "https://api.1tx.fi/api/v1/transactions/buy" \
  -H "Authorization: Bearer <your_jwt>" \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "userAddress": "0x59F84Af036712AFe2fD0Ec77f4D9a6F0a612f1fE",
    "instrumentId": "0x0000a4b194d4938ed6aab5bdbac7ca4b622f3639b1bca1b8b9c3271403d3b1b5",
    "amountUsdc": "2.20",
    "slippageBps": 50,
    "referralFeeBps": 25,
    "referralWallet": "0xYourReferralWallet"
  }'
```

### Response

```json theme={null}
{
  "sourceChainId": 8453,
  "destinationChainId": 42161,
  "isCrossChain": true,
  "transactions": [
    {
      "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "data": "0x095ea7b3...",
      "value": "0",
      "chainId": 8453,
      "type": "approve",
      "gasEstimate": "45000",
      "description": "Approve USDC"
    },
    {
      "to": "0xbFdd5bEdC0cB9B8795A93C2a1fB634012C8F99bC",
      "data": "0x...",
      "value": "0",
      "chainId": 8453,
      "type": "deposit",
      "gasEstimate": "300000",
      "description": "Bridge & Buy USDC"
    }
  ],
  "quote": {
    "amountIn": "2200000",
    "expectedOut": "2200000",
    "minOut": "2200000",
    "priceImpactBps": 0,
    "needsSwap": false
  },
  "expiresAt": 1775747400
}
```

### Response Fields

| Field                  | Type    | Description                                                    |
| ---------------------- | ------- | -------------------------------------------------------------- |
| `sourceChainId`        | number  | Chain where the returned transactions must be sent             |
| `destinationChainId`   | number  | Chain where the target instrument lives                        |
| `isCrossChain`         | boolean | `true` when the source chain differs from the instrument chain |
| `transactions`         | array   | Transactions to execute in order                               |
| `transactions[].type`  | string  | `approve` or `deposit`                                         |
| `quote.amountIn`       | string  | Input amount in raw USDC units                                 |
| `quote.expectedOut`    | string  | Expected destination-side output in raw units                  |
| `quote.minOut`         | string  | Minimum acceptable output after slippage                       |
| `quote.priceImpactBps` | number  | Estimated price impact in basis points                         |
| `quote.needsSwap`      | boolean | Whether the destination-side deposit requires a swap           |
| `expiresAt`            | number  | Unix timestamp after which the bundle should be rebuilt        |

### Notes

* The approval transaction is only included when current allowance is insufficient.
* For cross-chain buys, the router transaction still runs on the **source chain**.
* The returned calldata already includes the correct `fastTransfer` / `maxFee` parameters expected by the current router flow.
* When `referralFeeBps > 0`, the fee is deducted from the user's USDC input before swap and deposit. `referralWallet` must be a non-zero address. The router caps the referral fee at 500 bps (5%).

***

## Build Sell Transaction

<span style={{color: '#EAB308', fontWeight: 'bold'}}>POST</span> `/transactions/sell`

Build a transaction bundle that calls router `sell()` for a 1tx instrument.

Withdrawals are currently **same-chain only**.

### Request Body

| Field              | Type   | Required | Description                                                                                                                    |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `userAddress`      | string | Yes      | Wallet address that will sign the transactions                                                                                 |
| `instrumentId`     | string | Yes      | Instrument ID to withdraw from                                                                                                 |
| `yieldTokenAmount` | string | Yes      | Human-readable yield token amount, e.g. `"500.00"`                                                                             |
| `slippageBps`      | number | No       | Slippage tolerance in basis points. Defaults to `50`                                                                           |
| `referralFeeBps`   | number | No       | Referral fee in basis points (0–500, i.e. up to 5%), applied on the stable output. Defaults to `0`. Requires `referralWallet`. |
| `referralWallet`   | string | No       | Address that receives the referral fee. Required when `referralFeeBps > 0`.                                                    |

```bash theme={null}
curl -X POST "https://api.1tx.fi/api/v1/transactions/sell" \
  -H "Authorization: Bearer <your_jwt>" \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "userAddress": "0x59F84Af036712AFe2fD0Ec77f4D9a6F0a612f1fE",
    "instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
    "yieldTokenAmount": "500.00",
    "referralFeeBps": 25,
    "referralWallet": "0xYourReferralWallet"
  }'
```

### Response

```json theme={null}
{
  "sourceChainId": 8453,
  "destinationChainId": 8453,
  "isCrossChain": false,
  "transactions": [
    {
      "to": "0x4e65fE4DbA92790696d040ac24Aa414708F5c0AB",
      "data": "0x095ea7b3...",
      "value": "0",
      "chainId": 8453,
      "type": "approve",
      "gasEstimate": "47000",
      "description": "Approve aBasUSDC"
    },
    {
      "to": "0xbFdd5bEdC0cB9B8795A93C2a1fB634012C8F99bC",
      "data": "0x...",
      "value": "0",
      "chainId": 8453,
      "type": "withdraw",
      "gasEstimate": "280000",
      "description": "Sell USDC"
    }
  ],
  "quote": {
    "amountIn": "500000000000000000000",
    "expectedOut": "500000000",
    "minOut": "497500000",
    "priceImpactBps": 50,
    "needsSwap": false
  },
  "expiresAt": 1775747400
}
```

***

## Get User Balances

<span style={{color: '#10B981', fontWeight: 'bold'}}>GET</span> `/transactions/balances/:userAddress`

Scan supported chains for the user's USDC balance. This is useful when you want to show source-chain selection before calling `POST /transactions/buy`.

```bash theme={null}
curl "https://api.1tx.fi/api/v1/transactions/balances/0x59F84Af036712AFe2fD0Ec77f4D9a6F0a612f1fE" \
  -H "Authorization: Bearer <your_jwt>" \
  -H "x-api-key: <your_api_key>"
```

### Response

```json theme={null}
{
  "address": "0x59F84Af036712AFe2fD0Ec77f4D9a6F0a612f1fE",
  "balances": [
    {
      "chainId": 8453,
      "chainName": "Base Mainnet",
      "usdcBalance": "1500.0",
      "usdcBalanceRaw": "1500000000"
    },
    {
      "chainId": 42161,
      "chainName": "Arbitrum One",
      "usdcBalance": "500.0",
      "usdcBalanceRaw": "500000000"
    }
  ],
  "totalUsdcUsd": "2000.0"
}
```

***

## Recommended Execution Flow

For same-chain buys:

1. Call `POST /transactions/buy`.
2. Execute returned transactions in order.

For cross-chain buys:

1. Call `POST /transactions/buy`.
2. Execute returned transactions in order on `sourceChainId`.
3. Wait for the source router transaction hash.
4. Poll `GET /cctp/relay/tx/:sourceTxHash` until the bridge job reaches a terminal state.

<Tip>
  Do not call the legacy operation-confirmation endpoints for new integrations. The current production path is stateless transaction building plus CCTP relay status lookup by source transaction hash.
</Tip>

***

## Legacy Endpoints

The following endpoints still exist for backwards compatibility with older clients, but are not part of the recommended integration path:

* `POST /transactions/operations/:operationId/confirm`
* `GET /transactions/operations/:operationId`

New integrations should rely on transaction bundles and the CCTP API instead.