Skip to main content

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.

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

FieldTypeRequiredDescription
userAddressstringYesWallet address that will sign the transactions
instrumentIdstringYesTarget instrument ID
amountUsdcstringYesDeposit amount in human-readable USDC, e.g. "1000.50"
sourceChainIdnumberNoForce a specific source chain instead of auto-selecting from balances
slippageBpsnumberNoSlippage tolerance in basis points. Defaults to 50
referralFeeBpsnumberNoReferral fee in basis points (0–500, i.e. up to 5%). Defaults to 0. Requires referralWallet.
referralWalletstringNoAddress 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

FieldTypeDescription
sourceChainIdnumberChain where the returned transactions must be sent
destinationChainIdnumberChain where the target instrument lives
isCrossChainbooleantrue when the source chain differs from the instrument chain
transactionsarrayTransactions to execute in order
transactions[].typestringapprove or deposit
quote.amountInstringInput amount in raw USDC units
quote.expectedOutstringExpected destination-side output in raw units
quote.minOutstringMinimum acceptable output after slippage
quote.priceImpactBpsnumberEstimated price impact in basis points
quote.needsSwapbooleanWhether the destination-side deposit requires a swap
expiresAtnumberUnix 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

FieldTypeRequiredDescription
userAddressstringYesWallet address that will sign the transactions
instrumentIdstringYesInstrument ID to withdraw from
yieldTokenAmountstringYesHuman-readable yield token amount, e.g. "500.00"
slippageBpsnumberNoSlippage tolerance in basis points. Defaults to 50
referralFeeBpsnumberNoReferral fee in basis points (0–500, i.e. up to 5%), applied on the stable output. Defaults to 0. Requires referralWallet.
referralWalletstringNoAddress 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"
}
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.
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.