Submit and wait

POST /api/submit-tx-sync

Queue a gas-sponsored transaction and hold the request open until the transaction reaches a terminal status (EXECUTED or FAILED), until a transaction hash is available when returnOnTxHash is true, or until timeoutMs elapses. A completed wait returns 200 with the full transaction record; a timed-out wait returns 202 with the same record shape plus timedOut set to true, and the transaction continues to be relayed in the background. timeoutMs must be between 1000 and 120000.

Authentication

Send your API key in the api-key header.

Parameters

Name	In	Type	Required	Description
X-Edith-Region	header	string	no	Pin the relaying region explicitly. Takes precedence over the request body's region field. When neither is set (or the named region is inactive), the region is derived from the caller's country - via a trusted CDN country header or GeoIP - and falls back to the deployment's default region. Region names that are not active on this deployment are ignored.

Request body (application/json)

{
  "tx": {
    "to": "0xA7A833e6641D7901F30EaD6f27d4Ee2C9bb670a7",
    "callData": "0x",
    "chainId": 8453,
    "value": "1",
    "label": "sync-ping"
  },
  "timeoutMs": 30000,
  "includeReceipt": true,
  "includeRevertInfo": true,
  "returnOnTxHash": false
}

Responses

Status	Description
200	The transaction reached a terminal status (or produced a hash when returnOnTxHash is true) within the timeout.
202	The wait timed out before the transaction completed. The record is returned with timedOut set to true and the transaction keeps being relayed; poll GET /api/tx for the final status.
400	Invalid request. Plausible codes: VALIDATION_004 (schema validation failed, including timeoutMs outside 1000-120000), TRANSACTION_005 (invalid gas parameters), VALIDATION_003, CHAIN_001, TRANSACTION_001, TRANSACTION_002, TRANSACTION_006.
401	Authentication failed. Plausible codes: AUTH_002 (invalid API key).
404	The queued transaction could not be found when its status was looked up. Plausible codes: TRANSACTION_003.
429	Rate limit exceeded for this API key. Plausible codes: RESOURCE_003.
500	Server error. Plausible codes: SYSTEM_001, SYSTEM_002.

200 response

{
  "success": true,
  "data": {
    "id": "68fa3450539a3c9d28bbca33",
    "userId": "68c275846a6ba1c9a2198a8c",
    "to": "0xA7A833e6641D7901F30EaD6f27d4Ee2C9bb670a7",
    "callData": "0x",
    "value": "1",
    "chainId": 8453,
    "gasPrice": null,
    "maxFeePerGas": null,
    "maxPriorityFeePerGas": null,
    "gasLimit": "21000",
    "label": "sync-ping",
    "status": "EXECUTED",
    "executionTxHash": "0x8b6d34f1a2c05e97d0c1b28fe6a4a1c9e3b7d20a54f8c96e1d3a5b7c9e0f2a4b",
    "timestamp": "2026-07-29T12:35:02.114Z",
    "latency": 2500,
    "costUSD": 0.84,
    "retries": 0,
    "isAccountCharged": true,
    "transactionType": "flash",
    "submitRegion": "eu-west"
  },
  "timestamp": "2026-07-29T12:35:02.240Z"
}

202 response

{
  "success": true,
  "data": {
    "id": "68fa3450539a3c9d28bbca33",
    "userId": "68c275846a6ba1c9a2198a8c",
    "to": "0xA7A833e6641D7901F30EaD6f27d4Ee2C9bb670a7",
    "callData": "0x",
    "value": "1",
    "chainId": 8453,
    "gasPrice": null,
    "maxFeePerGas": null,
    "maxPriorityFeePerGas": null,
    "gasLimit": null,
    "label": "sync-ping",
    "status": "PENDING",
    "executionTxHash": null,
    "timestamp": "2026-07-29T12:35:29.871Z",
    "latency": null,
    "costUSD": null,
    "retries": 0,
    "isAccountCharged": false,
    "transactionType": "flash",
    "submitRegion": "eu-west",
    "timedOut": true
  },
  "timestamp": "2026-07-29T12:35:30.002Z"
}

400 response

{
  "success": false,
  "error": {
    "code": "VALIDATION_004",
    "message": "timeoutMs must be between 1000 and 120000",
    "category": "VALIDATION",
    "traceId": "6f2c1e0a-8b4d-4c1e-9f3a-2d5b7c8e9a01"
  },
  "timestamp": "2026-07-29T12:34:56.789Z"
}

401 response

{
  "success": false,
  "error": {
    "code": "AUTH_002",
    "message": "Invalid API key provided",
    "category": "AUTH",
    "traceId": "6f2c1e0a-8b4d-4c1e-9f3a-2d5b7c8e9a01"
  },
  "timestamp": "2026-07-29T12:34:56.789Z"
}

404 response

{
  "success": false,
  "error": {
    "code": "TRANSACTION_003",
    "message": "Transaction not found",
    "category": "TRANSACTION",
    "traceId": "6f2c1e0a-8b4d-4c1e-9f3a-2d5b7c8e9a01"
  },
  "timestamp": "2026-07-29T12:34:56.789Z"
}

429 response

{
  "success": false,
  "error": {
    "code": "RESOURCE_003",
    "message": "Resource limit exceeded",
    "category": "RESOURCE",
    "traceId": "6f2c1e0a-8b4d-4c1e-9f3a-2d5b7c8e9a01"
  },
  "timestamp": "2026-07-29T12:34:56.789Z"
}

500 response

{
  "success": false,
  "error": {
    "code": "SYSTEM_001",
    "message": "Database operation failed",
    "category": "SYSTEM",
    "traceId": "6f2c1e0a-8b4d-4c1e-9f3a-2d5b7c8e9a01"
  },
  "timestamp": "2026-07-29T12:34:56.789Z"
}