Transactions API

The Transactions API allows you to send, monitor, and manage blockchain transactions through rrelayer.

Authentication

All transaction endpoints require authentication. See Authentication for details.

Send Transaction

Send a new transaction through a relayer.

Endpoint

POST /transactions/relayers/{relayer_id}/send

Request Body

{
  "to": "0x1234567890abcdef1234567890abcdef12345678",
  "value": "1000000000000000000",
  "data": "0xa9059cbb000000000000000000000000...",
  "speed": "MEDIUM",
  "externalId": "order_12345",
  "blobs": ["0x01234567..."]
}

Parameters

Field	Type	Required	Description
`to`	`string`	Yes	Recipient address
`value`	`string`	No	Transaction value in wei (default: "0")
`data`	`string`	No	Transaction data/input (default: "0x")
`speed`	`string`	No	Transaction speed: `"SLOW"`, `"MEDIUM"`, `"FAST"`, `"SUPER"`
`externalId`	`string`	No	Custom external ID for tracking
`blobs`	`string[]`	No	Blob data for EIP-4844 transactions

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "hash": "0xabcdef123456789abcdef123456789abcdef123456789abcdef123456789abcdef"
}

Example

curl -X POST https://your-rrelayer.com/transactions/relayers/0x742d35.../send \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "0x1234567890abcdef1234567890abcdef12345678",
    "value": "1000000000000000000",
    "speed": "MEDIUM",
    "externalId": "order_12345"
  }'

Get Transaction

Get transaction details by ID.

Endpoint

GET /transactions/{transaction_id}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "relayerId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "to": "0x1234567890abcdef1234567890abcdef12345678",
  "from": "0x742d35cc6466c4b0de3e3e8c7b8e8f9e8a8d8c8b",
  "value": "1000000000000000000",
  "data": "0xa9059cbb000000000000000000000000...",
  "chainId": 11155111,
  "status": "CONFIRMED",
  "txHash": "0xabcdef123456789abcdef123456789abcdef123456789abcdef123456789abcdef",
  "queuedAt": "2025-09-26T10:29:30Z",
  "sentAt": "2025-09-26T10:30:00Z",
  "minedAt": "2025-09-26T10:31:30Z",
  "confirmedAt": "2025-09-26T10:32:00Z",
  "expiresAt": "2025-09-26T11:30:00Z",
  "externalId": "order_12345",
  "nonce": 42,
  "speed": "MEDIUM",
  "isNoop": false,
  "cancelledByTransactionId": null
}

Additional Fields for Cancelled Transactions

For transactions with status CANCELLED, additional fields are included:

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "CANCELLED",
  "isNoop": true,
  "cancelledByTransactionId": "550e8400-e29b-41d4-a716-446655440002",
  ...
}

Example

curl https://your-rrelayer.com/transactions/550e8400-e29b-41d4-a716-446655440000 \
  -u "username:password"

Get Transaction Status

Get the current status and receipt information for a transaction.

Endpoint

GET /transactions/status/{transaction_id}

Response

{
  "hash": "0xabcdef123456789abcdef123456789abcdef123456789abcdef123456789abcdef",
  "status": "CONFIRMED",
  "receipt": {
    "transactionHash": "0xabcdef...",
    "blockNumber": "0x123456",
    "blockHash": "0xfedcba...",
    "gasUsed": "0x5208",
    "status": "0x1",
    "logs": []
  }
}

Transaction Statuses

Status	Description
`PENDING`	Transaction is queued and waiting to be sent
`INMEMPOOL`	Transaction has been sent to the blockchain mempool
`MINED`	Transaction has been included in a block
`CONFIRMED`	Transaction has reached required confirmations
`FAILED`	Transaction failed on-chain
`EXPIRED`	Transaction expired before being mined
`CANCELLED`	Transaction was cancelled by a cancel operation
`REPLACED`	Transaction was replaced by a replace operation
`DROPPED`	Transaction was dropped from mempool (e.g., failed cancel/replace)

Example

curl https://your-rrelayer.com/transactions/status/550e8400-e29b-41d4-a716-446655440000 \
  -u "username:password"

Replace Transaction

Replace a pending or in-mempool transaction with new transaction parameters.

Endpoint

PUT /transactions/replace/{transaction_id}

Request Body

{
  "to": "0x1234567890abcdef1234567890abcdef12345678",
  "value": "2000000000000000000",
  "data": "0xa9059cbb000000000000000000000000...",
  "speed": "FAST"
}

Behavior

PENDING transactions: Original transaction parameters are updated in-place and marked with new values
INMEMPOOL transactions: A replacement transaction is created with the same nonce and higher gas price to compete on-chain
- If replacement transaction wins: Original becomes REPLACED, replacement transaction becomes MINED
- If original transaction wins: Original becomes MINED, replacement transaction becomes DROPPED

Response

{
  "success": true,
  "replaceTransactionId": "550e8400-e29b-41d4-a716-446655440003",
  "replaceTransactionHash": "0xdef456ghi789def456ghi789def456ghi789def456ghi789def456ghi789def456"
}

Fields

Field	Type	Description
`success`	`boolean`	Whether the replacement operation was successful
`replaceTransactionId`	`string`	UUID of the replacement transaction created (null if failed)
`replaceTransactionHash`	`string`	Transaction hash of the replacement transaction (null if PENDING or failed)

Note: For PENDING transactions that are replaced immediately, the response contains the same transaction ID with updated parameters, and hash will be null until sent.

Example

curl -X PUT https://your-rrelayer.com/transactions/replace/550e8400-e29b-41d4-a716-446655440000 \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "0x1234567890abcdef1234567890abcdef12345678",
    "value": "2000000000000000000",
    "speed": "FAST"
  }'

Cancel Transaction

Cancel a pending or in-mempool transaction.

Endpoint

PUT /transactions/cancel/{transaction_id}

Behavior

PENDING transactions: Immediately removed from queue and marked as CANCELLED
INMEMPOOL transactions: A cancel transaction is created with the same nonce and higher gas price to compete on-chain
- If cancel transaction wins: Original becomes CANCELLED, cancel transaction becomes MINED
- If original transaction wins: Original becomes MINED, cancel transaction becomes DROPPED

Response

{
  "success": true,
  "cancelTransactionId": "550e8400-e29b-41d4-a716-446655440004"
}

Fields

Field	Type	Description
`success`	`boolean`	Whether the cancel operation was successful
`cancelTransactionId`	`string`	UUID of the cancel transaction created (null if failed)

Note: For PENDING transactions that are cancelled immediately, no competing transaction is created on-chain.

Example

curl -X PUT https://your-rrelayer.com/transactions/cancel/550e8400-e29b-41d4-a716-446655440000 \
  -u "username:password"

Get Relayer Transactions

Get all transactions for a specific relayer.

Endpoint

GET /transactions/relayers/{relayer_id}

Query Parameters

Parameter	Type	Description
`limit`	`number`	Maximum number of transactions to return
`offset`	`number`	Number of transactions to skip
`status`	`string`	Filter by transaction status

Response

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "relayerId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "to": "0x1234567890abcdef1234567890abcdef12345678",
      "from": "0x742d35cc6466c4b0de3e3e8c7b8e8f9e8a8d8c8b",
      "value": "1000000000000000000",
      "data": "0x",
      "nonce": 42,
      "chainId": 11155111,
      "status": "CONFIRMED",
      "txHash": "0xabcdef...",
      "queuedAt": "2025-09-26T10:29:30Z",
      "expiresAt": "2025-09-26T11:30:00Z",
      "sentAt": "2025-09-26T10:30:00Z",
      "minedAt": "2025-09-26T10:31:30Z",
      "confirmedAt": "2025-09-26T10:32:00Z",
      "speed": "MEDIUM",
      "isNoop": false,
      "externalId": "order_12345"
    }
  ],
  "next": {
    "limit": 10,
    "offset": 10
  },
  "previous": null
}

Example

curl "https://your-rrelayer.com/transactions/relayers/0x742d35...?limit=10&offset=0" \
  -u "username:password"

Get Transaction Counts

Get pending and in-mempool transaction counts for a relayer.

Pending Count

GET /transactions/relayers/{relayer_id}/pending/count

In-Mempool Count

GET /transactions/relayers/{relayer_id}/inmempool/count

Response

{
  "count": 5
}

Example

curl https://your-rrelayer.com/transactions/relayers/0x742d35.../pending/count \
  -u "username:password"

Error Responses

Common Error Codes

Status	Code	Description
400	`INVALID_REQUEST`	Invalid request parameters
401	`UNAUTHORIZED`	Authentication required
403	`FORBIDDEN`	Insufficient permissions
404	`NOT_FOUND`	Transaction or relayer not found
429	`RATE_LIMIT_EXCEEDED`	Rate limit exceeded
500	`INTERNAL_ERROR`	Server error

Transaction Competition and Race Conditions

When cancelling or replacing transactions that are already in the blockchain mempool (status INMEMPOOL), rrelayer creates competing transactions with the same nonce and higher gas prices.

Competition Resolution

The blockchain will only mine one transaction per nonce. The resolution depends on which transaction gets mined first:

Cancel Operations

Cancel wins: Original transaction becomes CANCELLED with is_noop: true and cancelled_by_transaction_id set
Original wins: Original transaction becomes MINED, cancel transaction becomes DROPPED

Replace Operations

Replacement wins: Original transaction becomes REPLACED, replacement transaction becomes MINED
Original wins: Original transaction becomes MINED, replacement transaction becomes DROPPED

Monitoring Competition Results

You can monitor the outcome by:

Checking transaction status of the original transaction
Following the relationship using cancelled_by_transaction_id field
Monitoring both transactions if you need to track the competing transaction

Example: Monitoring a Cancel Operation

# 1. Send a transaction
POST /transactions/relayers/{relayer_id}/send
# Response: {"id": "550e8400-e29b-41d4-a716-446655440000", "hash": "0x..."}
 
# 2. Cancel the transaction (while INMEMPOOL)
PUT /transactions/cancel/550e8400-e29b-41d4-a716-446655440000
# Response: {"success": true, "cancelTransactionId": "550e8400-e29b-41d4-a716-446655440001"}
 
# 3. Monitor the original transaction status
GET /transactions/status/550e8400-e29b-41d4-a716-446655440000
# Possible outcomes:
# - "status": "CANCELLED" (cancel won)
# - "status": "MINED" (original won)
 
# 4. If cancelled, check the relationship
GET /transactions/550e8400-e29b-41d4-a716-446655440000
# Response includes: "cancelledByTransactionId": "550e8400-e29b-41d4-a716-446655440001"

Rate Limiting

Transaction endpoints are subject to rate limiting. See Rate Limits for configuration details.

Use the x-rrelayer-rate-limit-key header to specify a custom rate limit key:

curl -X POST https://your-rrelayer.com/transactions/relayers/0x742d35.../send \
  -H "x-rrelayer-rate-limit-key: user-12345" \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{"to": "0x...", "value": "1000000000000000000"}'