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
Authentication
A JWT Token is required to make requests to the Relay API. For security reasons authentication uses SRP protocol and it is not possible to retrieve a JWT Token via a single HTTP request, which is why it is advised to use the Amazon Cognito User Pool SDK to retrieve a JWT token.
Note that if you are using the defender-relay-client all authentication is automatically handled for you by supplying the API key and secret.
Python Authentication
The official AWS SDK for python doesn’t support SRP authentication, but it is possible to retrieve a JWT token using the warrant library.
Here is an example:
import boto3
from warrant.aws_srp import AWSSRP
client = boto3.client('cognito-idp', region_name='us-west-2')
aws = AWSSRP(username='API_KEY', password='API_SECRET', pool_id='us-west-2_iLmIggsiy', client_id='1bpd19lcr33qvg5cr3oi79rdap', client=client)
tokens = aws.authenticate_user()
print('Access Token', tokens['AuthenticationResult']['AccessToken'])
Refreshing JWT Token
A JWT token will expire in 60 minutes. If your code requires sessions longer than 60 minutes consider recreating a JWT token or using a refresh token.
Making Authenticated Requests
Once you get a JWT Token you can make requests to the Defender API. A request requires an API key, a JWT Token, optionally a payload, and an API URL. Set $KEY
, $TOKEN
to the values of API key and JWT Token acquired before. $END_POINT
can be either txs
or sign
.
API_URL='http://api.defender.openzeppelin.com/'
curl \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "X-Api-Key: $KEY" \
-H "Authorization: Bearer $TOKEN" \
"$API_URL/$END_POINT"
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:
export type Address = string;
export type BigUInt = string | number;
export type Hex = string;
export type Speed = 'safeLow' | 'average' | 'fast' | 'fastest';
export 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" \
"$API_URL/txs" # http://api.defender.openzeppelin.com/txs
You would receive a response in the following format:
export type Address = string;
export type BigUInt = string | number;
export type Hex = string;
export type Speed = 'safeLow' | 'average' | 'fast' | 'fastest';
export type Status = 'pending' | 'sent' | 'submitted' | 'inmempool' | 'mined' | 'confirmed';
export interface TransactionResponse {
transactionId: string; // Defender tx id
hash: string; // Ethereum hash
to: Address;
from: Address;
value: string;
data: string;
speed: Speed;
gasPrice: number;
gasLimit: number;
nonce: number;
status: Status;
chainId: number;
validUntil: string;
}
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" \
"$API_URL/txs/$ID" # http://api.defender.openzeppelin.com/txs/affba150-e563-441e-ae49-04bd6050979a
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:
export 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" \
"$API_URL/sign" # http://api.defender.openzeppelin.com/sign
You would receive a response in the following format:
export 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" \
"$API_URL/relayer" # http://api.defender.openzeppelin.com/relayer
You would receive a response in the following format:
export 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" \
"$API_URL/relayer/jsonrpc" # http://api.defender.openzeppelin.com/relayer/jsonrpc
An example of the response:
{
"id": 1,
"jsonrpc": "2.0",
"result": "0x0234c8a3397aab58"
}