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

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
500	`INTERNAL_ERROR`	Server error

Authentication

Create Relayer

Endpoint

Request Body

Parameters

Response

Example

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