Relay API Reference
The Relay API exposes the following endpoints:
-
txs
: send transactions to the Ethereum blockchain and query their status -
sign
: sign arbitrary data with relayer’s private key -
relayer
: retrieve information from the relayer -
jsonrpc
: make json-rpc calls to the Ethereum network
All requests need to be authenticated with a bearer token, which is generated using a Relayer API Key. Refer to the authentication section for info on how to negotiate it.
You can use the defender-relay-client npm package for simplifying interactions with the Relay API. |
Transactions Endpoint
The /txs
endpoint is used for both sending transactions and for retrieving transaction information given a transaction identifier.
Send Transaction
To send a transaction to the Ethereum blockchain submit a POST
request with the desired payload. The payload format is as follows:
type Address = string;
type BigUInt = string | number;
type Hex = string;
type Speed = 'safeLow' | 'average' | 'fast' | 'fastest';
interface SendTransactionRequest {
to: Address;
value?: BigUInt; // optional
data?: Hex; // optional
speed?: Speed; // optional
gasPrice?: BigUInt; // optional
validUntil?: string; // optional
gasLimit: BigUInt;
}
An example of the request:
DATA='{ "to": "0x179810822f56b0e79469189741a3fa5f2f9a7631", "value": "1", "speed": "fast", "gasLimit": "21000" }'
curl \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "X-Api-Key: $KEY" \
-H "Authorization: Bearer $TOKEN" \
-d "$DATA" \
"https://api.defender.openzeppelin.com/txs"
You would receive a response in the following format:
type Address = string;
type BigUInt = string | number;
type Hex = string;
type Speed = 'safeLow' | 'average' | 'fast' | 'fastest';
type Status = 'pending' | 'sent' | 'submitted' | 'inmempool' | 'mined' | 'confirmed';
interface TransactionResponse {
transactionId: string;
hash: string;
to: Address;
from: Address;
value: string;
data: string;
speed: Speed;
gasPrice: number;
gasLimit: number;
nonce: number;
status: Status;
chainId: number;
validUntil: string;
}
Note the extra transactionId
field, which is an internal Defender identifier for the transaction, which is used for querying.
Query Transaction
To retrieve a transaction status and data make a GET
request to the txs
endpoint with the Defender transactionId
, not with the transaction hash.
An example of the request:
curl \
-X GET \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "X-Api-Key: $KEY" \
-H "Authorization: Bearer $TOKEN" \
"https://api.defender.openzeppelin.com/txs/$ID"
An example of the response:
{
"chainId":4,
"hash":"0xcef95469a9f02757f0968ec8c11449ae5e7486073075381dcd62bacec9e5d627",
"transactionId":"affba150-e563-441e-ae49-04bd6050979a",
"value":"0x1",
"gasPrice":1000000000,
"gasLimit":21000,
"to":"0x179810822f56b0e79469189741a3fa5f2f9a7631",
"from":"0xbce0b5b71668e42d908e387b68dba91789c932b8",
"data":"0x",
"nonce":160,
"status":"mined",
"speed":"fast"
}
Sign Endpoint
To sign arbitrary data with your Relay private key make a POST
request to /sign
with a payload containing the hex string to sign. The payload format is:
interface SignMessagePayload {
message: Hex;
}
An example of the request:
DATA='{ "message": "0x0123456789abcdef" }'
curl \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "X-Api-Key: $KEY" \
-H "Authorization: Bearer $TOKEN" \
-d "$DATA" \
"https://api.defender.openzeppelin.com/sign"
You would receive a response in the following format:
interface SignedMessagePayload {
sig: Hex;
r: Hex;
s: Hex;
v: number;
}
An example of the response:
{
"r":"0x819b2645a0b73494724dac355e6ecfc983d94597b533d34fe3ecd0277046a1eb",
"s":"0x3b73c695b47dd275d17246d86bbfe35f112a7bdb5bf4a5a1a8e22fe37dfd005a",
"v":44,
"sig":"0x819b2645a0b73494724dac355e6ecfc983d94597b533d34fe3ecd0277046a1eb3b73c695b47dd275d17246d86bbfe35f112a7bdb5bf4a5a1a8e22fe37dfd005a2c"
}
Relayer Endpoint
To retrieve a relayer’s data with the Relay API make a GET
request to the /relayer
endpoint.
An example of the request:
curl \
-X GET \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "X-Api-Key: $KEY" \
-H "Authorization: Bearer $TOKEN" \
"https://api.defender.openzeppelin.com/relayer"
You would receive a response in the following format:
interface RelayerModel {
relayerId: string;
name: string;
address: string;
network: string;
paused: boolean;
createdAt: string;
pendingTxCost: string;
}
An example of the response:
{
"relayerId":"d5484fb1-df83-4659-9903-16d57d41f188",
"name":"Rinkeby",
"address":"0x71764d6450c2b710fc3e4ee5b7a038d1e7e4fc29",
"network":"rinkeby",
"createdAt":"2020-11-02T18:00:00.212Z",
"paused":false,
"pendingTxCost":"0"
}
JSON RPC Endpoint
To make a JSON RPC call to the network of your Relay, make a POST
request to the /relayer/jsonrpc
endpoint with the method name and parameters. Note that event filter methods and websocket subscriptions are not supported.
An example of the request:
DATA='{ "jsonrpc":"2.0","method":"eth_getBalance","params":["0x407d73d8a49eeb85d32cf465507dd71d507100c1","latest"],"id":1 }'
curl \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "X-Api-Key: $KEY" \
-H "Authorization: Bearer $TOKEN" \
-d "$DATA" \
"https://api.defender.openzeppelin.com/relayer/jsonrpc"
An example of the response:
{
"id": 1,
"jsonrpc": "2.0",
"result": "0x0234c8a3397aab58"
}