Submit Signed Transaction API

Submit a pre-signed transaction to the Tachyon relay network. Tachyon will automatically fund the sender address with the required balance before broadcasting the transaction.

Endpoint


POST /api/submit-signed-tx

Authentication

This endpoint requires API key authentication via the api-key header.

Headers:


api-key: YOUR_API_KEY
Content-Type: application/json

Request Body

Field	Type	Required	Description
`signedTx`	`string`	Yes	The complete signed transaction data in hexadecimal format, ready for broadcast.
`minBalanceRequired`	`string`	Yes	The minimum balance required in the sender’s account (in smallest unit - wei for EVM). Typically `gasLimit * maxFeePerGas`.
`fromAddress`	`string`	Yes	The address that signed the transaction. Must be a valid address for the specified chain.
`chainId`	`number`	Yes	The blockchain network ID. Must be a supported chain.
`label`	`string`	No	Human-readable label for transaction identification and tracking.

Request Example

api-request.sh


curl -X POST https://api.tachyon.xyz/api/submit-signed-tx \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signedTx": "0x02f8730182...",
    "minBalanceRequired": "42000000000000",
    "fromAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "chainId": 8453,
    "label": "Token Transfer"
  }'

JavaScript Example:

submit-signed-tx.js


const response = await fetch('https://api.tachyon.xyz/api/submit-signed-tx', {
  method: 'POST',
  headers: {
    'api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    signedTx: '0x02f8730182...',
    minBalanceRequired: '42000000000000',
    fromAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
    chainId: 8453,
    label: 'Token Transfer',
  }),
})
 
const data = await response.json()
console.log('Transaction ID:', data.data.txId)

Response

Success Response (201 Created)

response.json


{
  "success": true,
  "data": {
    "txId": "671a2b4c539a3c9d28bbca33"
  },
  "error": null
}

Response Fields:

success (boolean): Indicates if the request was successful
data.txId (string): Unique transaction identifier for tracking
error (null): No error on success

Error Responses

400 Bad Request - Validation Error

Invalid Address:

error-response.json


{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_INVALID_ADDRESS",
    "message": "Invalid from address",
    "details": {
      "address": "0xinvalid"
    }
  }
}

Missing Required Field:

error-response.json


{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing signed transaction data"
  }
}

Unsupported Chain:

error-response.json


{
  "success": false,
  "data": null,
  "error": {
    "code": "CHAIN_UNSUPPORTED",
    "message": "Unsupported chainId",
    "details": {
      "chainId": 999999
    }
  }
}

401 Unauthorized

Invalid API Key:

error-response.json


{
  "success": false,
  "data": null,
  "error": {
    "code": "AUTH_UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Account Disabled:

error-response.json


{
  "success": false,
  "data": null,
  "error": {
    "code": "AUTH_UNAUTHORIZED",
    "message": "Account is disabled"
  }
}

403 Forbidden

Chain Disabled:

error-response.json


{
  "success": false,
  "data": null,
  "error": {
    "code": "CHAIN_UNSUPPORTED",
    "message": "Chain is disabled for this account",
    "details": {
      "chainId": 8453
    }
  }
}

Cost Exceeded:

error-response.json


{
  "success": false,
  "data": null,
  "error": {
    "code": "TRANSACTION_COST_EXCEEDED",
    "message": "Transaction cost exceeds maximum allowed",
    "details": {
      "estimatedCost": 15.5,
      "maxFee": 10.0
    }
  }
}

Insufficient Balance:

error-response.json


{
  "success": false,
  "data": null,
  "error": {
    "code": "TRANSACTION_INSUFFICIENT_BALANCE",
    "message": "Insufficient account balance",
    "details": {
      "requiredBalance": 10.5,
      "availableBalance": 5.0
    }
  }
}

Daily Limit Exceeded:

error-response.json


{
  "success": false,
  "data": null,
  "error": {
    "code": "TRANSACTION_DAILY_LIMIT_EXCEEDED",
    "message": "Daily spending limit exceeded",
    "details": {
      "requiredDailyLimit": 150.0,
      "currentDailyLimit": 100.0
    }
  }
}

How It Works

Authentication: Your API key is validated and account status is checked
Validation: Request body is validated against the schema, including address format
Cost Estimation: Funding cost is calculated based on minBalanceRequired and current token prices
Limit Checks: Per-transaction and daily spending limits are verified
Balance Check: Your Tachyon account balance is verified against the funding cost
Transaction Creation: A funding-signed transaction is created with status NOT_PICKED_UP
Queue Submission: Transaction is added to the relay queue for processing
Response: Transaction ID is returned for status tracking

Cost Calculation

The cost for a signed transaction includes:

Funding Cost: The minBalanceRequired converted to USD using current token prices
Service Fee: 8% markup applied to the funding cost

Formula:


Total Cost (USD) = minBalanceRequired (in native tokens) × Token Price (USD) × 1.08

Example (Base Mainnet):

example.js


// Transaction details
gasLimit = 21000
maxFeePerGas = 2 gwei (0.000000002 ETH)
minBalanceRequired = 21000 × 0.000000002 = 0.000042 ETH
 
// If ETH price = $3,000
fundingCost = 0.000042 × 3000 = $0.126
totalCost = $0.126 × 1.08 = $0.13608

Transaction Lifecycle

After submission, the transaction goes through these stages:

NOT_PICKED_UP: Transaction is queued and waiting to be processed
PENDING: Relay service is funding the address and preparing to broadcast
EXECUTED: Transaction has been broadcast and confirmed on-chain
FAILED: Transaction failed (with error details)

Track transaction status using the Get Relay Status API or the SDK status methods.

Rate Limits

This endpoint is subject to the following limits:

Account Balance: Must have sufficient balance for the funding cost
Per-Transaction Limit: Default $100 per transaction (configurable per account)
Daily Limit: Account-specific daily spending limit
Rate Limiting: Standard API rate limits apply

Notes

The fromAddress will be automatically funded with minBalanceRequired before broadcasting
The signed transaction must be valid and ready for broadcast
Ensure minBalanceRequired covers the maximum possible gas cost
Transaction type is automatically set to FUNDING_SIGNED
Sepolia testnet has a higher limit of $100 per transaction
Daily limits reset at midnight UTC