Custom Transactions

Submit a custom EVM contract call from a custodial wallet (calldata + optional native value). Xellar signs and broadcasts via MPC. Tron and other non-EVM networks are not supported on this route. All endpoints require authentication.

Method	Path
`POST`	`/api/v1/transactions`
`GET`	`/api/v1/transactions/:id`

Transaction object

Returned by Create and Get.

Field	Type	Description
`id`	string	Custom transaction UUID
`status`	string	`pending`, `queued`, `success`, or `failed`
`walletId`	string	Custodial wallet UUID that sends the transaction
`network`	string	Network code (e.g. `ethereum`, `polygon-pos`) — must be an active EVM network
`to`	string	Contract or recipient address (checksummed `0x…`)
`data`	string	Hex calldata (with or without `0x` prefix)
`value`	string	Native token sent with the call, in wei (integer string). Default `"0"`
`reference`	string \| null	Your optional reference
`transactionHash`	string \| null	On-chain tx hash when `status` is `success`
`failedReason`	string \| null	Human-readable reason when `status` is `failed`

Status lifecycle

Status	Meaning
`pending`	Signing / broadcast in progress for this wallet
`queued`	Another custom tx is in flight for the same wallet; starts when the active one finishes
`success`	Broadcast confirmed (`transactionHash` set)
`failed`	Signing or broadcast failed

Create Custom Transaction

POST /api/v1/transactions

Request body

Field	Type	Required	Description
`walletId`	string	Yes	Wallet UUID (must belong to your app’s account)
`network`	string	Yes	EVM network code (not token code)
`to`	string	Yes	Valid EVM address
`data`	string	Yes	Hex-encoded calldata
`value`	string	No	Wei to send (non-negative integer). Omitted = `0`
`reference`	string	No	Stored on the record; empty strings ignored
`gasTipCap`	string \| number	No	EIP-1559 tip cap in wei (optional override)
`gasFeeCap`	string \| number	No	EIP-1559 fee cap in wei (optional override)

{
  "walletId": "5326036c-50c3-4d63-8150-69cb253542e3",
  "network": "ethereum",
  "to": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  "data": "0xa9059cbb000000000000000000000000742d35Cc6634C0532925a3b844Bc454e4438f44e000000000000000000000000000000000000000000000000000000000016e360",
  "value": "0",
  "reference": "claim-reward-001"
}

Response `201`

{
  "data": {
    "id": "tx-uuid",
    "status": "pending",
    "walletId": "5326036c-50c3-4d63-8150-69cb253542e3",
    "network": "ethereum",
    "to": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    "data": "0xa9059cbb…",
    "value": "0",
    "reference": "claim-reward-001",
    "transactionHash": null,
    "failedReason": null
  }
}

Code	Meaning
400	Invalid wallet, network, address, calldata, value, or gas caps
404	Wallet or network not found
503	MPC signing unavailable

Get Custom Transaction

GET /api/v1/transactions/:id

:id is the UUID from Create.

Response `200`

Same object shape as Transaction object.

Code	Meaning
404	Transaction not found (or not owned by your app)

Assets & Balances KYC