Transactions API - 1tx Documentation

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:

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

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.

Build Buy Transaction

POST /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`.

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

{
  "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

POST /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`.

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

{
  "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

GET /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.

curl "https://api.1tx.fi/api/v1/transactions/balances/0x59F84Af036712AFe2fD0Ec77f4D9a6F0a612f1fE" \
  -H "Authorization: Bearer <your_jwt>" \
  -H "x-api-key: <your_api_key>"

Response

{
  "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:

Call POST /transactions/buy.
Execute returned transactions in order.

For cross-chain buys:

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

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.

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.

​Overview

​Build Buy Transaction

​Request Body

​Response

​Response Fields

​Notes

​Build Sell Transaction

​Request Body

​Response

​Get User Balances

​Response

​Recommended Execution Flow

​Legacy Endpoints

Overview

Build Buy Transaction

Request Body

Response

Response Fields

Notes

Build Sell Transaction

Request Body

Response

Get User Balances

Response

Recommended Execution Flow

Legacy Endpoints