Submit a transaction¶

POST /api/submit-tx

Queue a gas-sponsored transaction for asynchronous relaying and return immediately with a transaction id. The relayer estimates the cost, reserves it against your account balance, executes the call on chain, and settles the actual cost. Gas overrides are optional; provide either the legacy gasPrice or the EIP-1559 pair (maxFeePerGas together with maxPriorityFeePerGas) - never both. Poll GET /api/tx with the returned txId, or register webhooks/WebSocket to be notified on status changes.

On HyperCore chains (10200000 / 10200001), callData carries base64 of the complete signed exchange request {action, nonce, signature}; to/value/gas fields and authorizationList are rejected, and costUSD is always 0. Acceptance is synchronous: accepted actions land as EXECUTED immediately, rejections FAIL without retry.

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)

{
  "to": "0xA7A833e6641D7901F30EaD6f27d4Ee2C9bb670a7",
  "callData": "0xa9059cbb000000000000000000000000d6cedde84be40893d153be9d467cd6ad37875a280000000000000000000000000000000000000000000000000000000000989680",
  "chainId": 8453,
  "value": "0",
  "gasLimit": "120000",
  "maxUSD": 2.5,
  "label": "usdc-transfer-42",
  "transactionType": "flash"
}

Responses

Status	Description
`201`	Transaction accepted and queued for relaying.
`400`	Invalid request. Plausible codes: VALIDATION_004 (schema validation failed), TRANSACTION_005 (invalid gas parameters, e.g. gasPrice combined with EIP-1559 fields), VALIDATION_003 (flash-blocks on a chain other than Base or Base Sepolia), CHAIN_001 (unsupported chain), TRANSACTION_001 (cost limit exceeded), TRANSACTION_002 (insufficient balance), TRANSACTION_006 (daily limit exceeded).
`401`	Authentication failed. Plausible codes: AUTH_002 (an api-key header was sent but the key is invalid or revoked).
`429`	Rate limit exceeded for this API key. Plausible codes: RESOURCE_003.
`500`	Server error. Plausible codes: SYSTEM_001 (database operation failed), SYSTEM_002 (internal error).

201 response

{
  "success": true,
  "data": {
    "txId": "68fa3450539a3c9d28bbca33",
    "estimatedCostUSD": 0.84
  },
  "timestamp": "2026-07-29T12:34:56.789Z"
}

400 response

{
  "success": false,
  "error": {
    "code": "TRANSACTION_005",
    "message": "gasPrice cannot be combined with EIP-1559 fee fields",
    "category": "TRANSACTION",
    "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"
}

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