Relayers API

The Relayers API allows you to create, manage, and monitor relayer accounts that send transactions on behalf of your applications.

Authentication

All relayer endpoints require authentication. See Authentication for details.

Create Relayer

Create a new relayer for a specific blockchain network.

Endpoint

POST /relayers/{chain_id}/new

Request Body

{
  "name": "my-app-relayer"
}

Parameters

Field	Type	Required	Description
`name`	`string`	Yes	Human-readable name for the relayer

Response

{
  "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "address": "0x742d35cc6466c4b0de3e3e8c7b8e8f9e8a8d8c8b"
}

Example

curl -X POST https://your-rrelayer.com/relayers/11155111/new \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app-relayer"}'

Import Relayer

Import an existing signing key (e.g., AWS KMS key) as a relayer. This allows you to use pre-existing keys with rrelayer without manually creating database records or renaming key aliases.

Note: This endpoint is only available when using signing providers that support key import (currently AWS KMS).

Endpoint

POST /relayers/{chain_id}/import

Request Body

{
  "name": "my-imported-relayer",
  "keyId": "arn:aws:kms:us-east-1:123456789012:key/abc123-def456-ghi789",
  "address": "0x742d35cc6466c4b0de3e3e8c7b8e8f9e8a8d8c8b"
}

Parameters

Field	Type	Required	Description
`name`	`string`	Yes	Human-readable name for the relayer
`keyId`	`string`	Yes	The key identifier (format depends on provider, e.g., KMS key ARN for AWS)
`address`	`string`	Yes	The Ethereum address derived from the key (verified against the actual key)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "address": "0x742d35cc6466c4b0de3e3e8c7b8e8f9e8a8d8c8b",
  "walletIndex": 0,
  "keyAlias": "alias/rrelayer-wallet-0-11155111"
}

Response Fields

Field	Type	Description
`id`	`string`	Unique identifier for the imported relayer
`address`	`string`	Ethereum address of the relayer
`walletIndex`	`number`	Wallet index assigned to this relayer
`keyAlias`	`string`	The alias/identifier assigned to the key (e.g., KMS alias)

Validation

The endpoint performs the following validations:

Provider Support - Verifies the signing provider supports key import
Key Existence - Confirms the key exists and is accessible
Key Type - Validates the key is the correct type (e.g., ECC_SECG_P256K1 for AWS KMS)
Address Match - Verifies the provided address matches the key's actual address (before creating any side effects)
Duplicate Check - Returns 409 Conflict if a relayer with the same address already exists for this chain

Error Responses

Status	Description
400	Invalid request, key doesn't exist, or address mismatch
409	A relayer with this address already exists for the specified chain
500	Server error during key import

Example

curl -X POST https://your-rrelayer.com/relayers/11155111/import \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-imported-relayer",
    "keyId": "arn:aws:kms:us-east-1:123456789012:key/abc123-def456-ghi789",
    "address": "0x742d35cc6466c4b0de3e3e8c7b8e8f9e8a8d8c8b"
  }'

Use Cases

Migrating from another system - Import existing KMS keys from previous infrastructure
Using pre-configured keys - Import keys that were set up manually or via infrastructure-as-code
Key rotation - Import new keys while maintaining the same relayer configuration

Get Relayers

Get a list of all relayers.

Endpoint

GET /relayers

Query Parameters

Parameter	Type	Description
`limit`	`number`	Maximum number of relayers to return
`offset`	`number`	Number of relayers to skip
`chain_id`	`number`	Filter by chain ID

Response

{
  "items": [
    {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "name": "my-app-relayer",
      "chainId": 11155111,
      "address": "0x742d35cc6466c4b0de3e3e8c7b8e8f9e8a8d8c8b",
      "walletIndex": 1,
      "maxGasPrice": "50000000000",
      "paused": false,
      "eip1559Enabled": true,
      "isPrivateKey": false,
      "createdAt": "2025-09-26T10:00:00Z"
    }
  ],
  "next": {
    "limit": 10,
    "offset": 10
  },
  "previous": null
}

Example

curl "https://your-rrelayer.com/relayers?limit=10&chain_id=11155111" \
  -u "username:password"

Get Relayer

Get details for a specific relayer.

Endpoint

GET /relayers/{relayer_id}

Response

{
  "relayer": {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "name": "my-app-relayer",
    "chainId": 11155111,
    "address": "0x742d35cc6466c4b0de3e3e8c7b8e8f9e8a8d8c8b",
    "walletIndex": 1,
    "maxGasPrice": "50000000000",
    "paused": false,
    "eip1559Enabled": true,
    "isPrivateKey": false,
    "createdAt": "2025-09-26T10:00:00Z"
  },
  "providerUrls": ["https://sepolia.gateway.tenderly.co"]
}

Relayer Fields

Field	Type	Description
`paused`	`boolean`	Whether the relayer is paused
`eip1559Enabled`	`boolean`	Whether EIP-1559 transactions are enabled
`maxGasPrice`	`string`	Maximum gas price (optional)
`walletIndex`	`number`	Wallet index for key derivation
`isPrivateKey`	`boolean`	Whether relayer uses a private key vs mnemonic-derived

Example

curl https://your-rrelayer.com/relayers/6ba7b810-9dad-11d1-80b4-00c04fd430c8 \
  -u "username:password"

Clone Relayer

Create a copy of an existing relayer with the same configuration.

Endpoint

POST /relayers/{relayer_id}/clone

Request Body

{
  "newRelayerName": "cloned-relayer",
  "chainId": 1
}

Parameters

Field	Type	Required	Description
`newRelayerName`	`string`	Yes	Name for the cloned relayer
`chainId`	`number`	Yes	Target chain ID for the cloned relayer

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "address": "0x853e46dd7577c4c0df3f4e9f0b0e1f1f1c2d3e4f"
}

Example

curl -X POST https://your-rrelayer.com/relayers/6ba7b810-9dad-11d1-80b4-00c04fd430c8/clone \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{"newRelayerName": "cloned-relayer", "chainId": 1}'

Pause Relayer

Pause a relayer to stop it from sending new transactions.

Endpoint

PUT /relayers/{relayer_id}/pause

Response

{
  "message": "Relayer paused successfully"
}

Example

curl -X PUT https://your-rrelayer.com/relayers/6ba7b810-9dad-11d1-80b4-00c04fd430c8/pause \
  -u "username:password"

Unpause Relayer

Resume a paused relayer.

Endpoint

PUT /relayers/{relayer_id}/unpause

Response

{
  "message": "Relayer unpaused successfully"
}

Example

curl -X PUT https://your-rrelayer.com/relayers/6ba7b810-9dad-11d1-80b4-00c04fd430c8/unpause \
  -u "username:password"

Update Max Gas Price

Set the maximum gas price a relayer will use for transactions.

Endpoint

PUT /relayers/{relayer_id}/gas/max/{gas_price_cap}

Path Parameters

Parameter	Type	Description
`gas_price_cap`	`string`	Maximum gas price in wei

Response

{
  "message": "Max gas price updated successfully"
}

Example

curl -X PUT https://your-rrelayer.com/relayers/6ba7b810-9dad-11d1-80b4-00c04fd430c8/gas/max/50000000000 \
  -u "username:password"

Update EIP-1559 Status

Enable or disable EIP-1559 transaction types for a relayer.

Endpoint

PUT /relayers/{relayer_id}/gas/eip1559/{enabled}

Path Parameters

Parameter	Type	Description
`enabled`	`boolean`	`true` to enable EIP-1559, `false` to disable

Response

{
  "message": "EIP-1559 status updated successfully"
}

Example

curl -X PUT https://your-rrelayer.com/relayers/6ba7b810-9dad-11d1-80b4-00c04fd430c8/gas/eip1559/true \
  -u "username:password"

Get Allowlist Addresses

Get the list of allowed recipient addresses for a relayer.

Endpoint

GET /relayers/{relayer_id}/allowlists

Response

[
  "0x1234567890abcdef1234567890abcdef12345678",
  "0x9876543210fedcba9876543210fedcba98765432"
]

Example

curl https://your-rrelayer.com/relayers/6ba7b810-9dad-11d1-80b4-00c04fd430c8/allowlists \
  -u "username:password"

Delete Relayer

Delete a relayer permanently.

Endpoint

DELETE /relayers/{relayer_id}

Response

{
  "message": "Relayer deleted successfully"
}

Example

curl -X DELETE https://your-rrelayer.com/relayers/0x742d35cc6466c4b0de3e3e8c7b8e8f9e8a8d8c8b \
  -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`	Relayer not found
409	`CONFLICT`	Relayer name already exists or address already exists for chain
500	`INTERNAL_ERROR`	Server error

Authentication

Create Relayer

Endpoint

Request Body

Parameters

Response

Example

Import Relayer

Endpoint

Request Body

Parameters

Response

Response Fields

Validation

Error Responses

Example

Use Cases

Get Relayers

Endpoint

Query Parameters

Response

Example

Get Relayer

Endpoint

Response

Relayer Fields

Example

Clone Relayer

Endpoint

Request Body

Parameters

Response

Example

Pause Relayer

Endpoint

Response

Example

Unpause Relayer

Endpoint

Response

Example

Update Max Gas Price

Endpoint

Path Parameters

Response

Example

Update EIP-1559 Status

Endpoint

Path Parameters

Response

Example

Get Allowlist Addresses

Endpoint

Response

Example

Delete Relayer

Endpoint

Response

Example

Error Responses

Common Error Codes

Best Practices

Relayer Management

Performance Optimization