📨API

How to communicate directly with the Gelato Relay API

The Gelato Relay API endpoint URL is https://api.gelato.digital/

The Swagger UI is located at https://api.gelato.digital/api-docs

Oracle queries

Get list of chains where the oracle is available

GET/oracles

Response

200

Successful Retrieval

Body

application/json

oraclesarray of string

Request

JavaScriptCurlPython

const response = await fetch('/oracles', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "oracles": [
    "text"
  ]
}

Get the estimated fee in payment token with respect to the gas limit and priority

GET/oracles/{chainId}/estimate

Path parameters

chainId*number

Id of the chain where the fee is estimated

Query parameters

Response

200404

Successful Retrieval

Body

application/json

estimatedFee*string

decimals*number

Request

JavaScriptCurlPython

const response = await fetch('/oracles/{chainId}/estimate?paymentToken=text&gasLimit=0&isHighPriority=false', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "estimatedFee": "text",
  "decimals": 0
}

Get all the payment tokens on a chain

GET/oracles/{chainId}/paymentTokens

Path parameters

chainId*number

Id of the chain where payments tokens are retrieved

Response

200404

Successful Retrieval

Body

application/json

paymentTokensarray of string

Request

JavaScriptCurlPython

const response = await fetch('/oracles/{chainId}/paymentTokens', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "paymentTokens": [
    "text"
  ]
}

Get the conversion rate from the native token to the requested token

GET/oracles/{chainId}/conversionRate

Path parameters

chainId*number

Id of the chain where the conversion rate is estimated

Query parameters

Response

200400404

Successful Conversion Rate Response

Body

application/json

chainId*string

from*string

to*string

conversionRate*number (double)

details*object

Request

JavaScriptCurlPython

const response = await fetch('/oracles/{chainId}/conversionRate', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "chainId": "text",
  "from": "text",
  "to": "text",
  "conversionRate": 0,
  "details": {
    "numerator": "text",
    "denominator": "text"
  }
}

Relay Endpoints

Informational

Get list of chains where relay v2 is available

GET/relays/v2

Response

200

Successful Retrieval

Body

application/json

relaysarray of string

Request

JavaScriptCurlPython

const response = await fetch('/relays/v2', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "relays": [
    "text"
  ]
}

Sending Relay Requests:

Each relay request method possesses optional parameters such as the gasLimit , and retries. You can find more information on these on the Optional Parameters page.

/call-with-sync-fee/: for more information, please click here.

Place a relay v2 callWithSyncFee request

Please find more information here: https://docs.gelato.network/developer-products/gelato-relay-sdk/sdk-methods/relaywithsyncfee

POST/relays/v2/call-with-sync-fee

Body

application/json

chainId*number

target*string

data*string

feeToken*string

sponsorApiKeystring

gasLimitstring

retriesnumber

Response

201400404

Successfully placed a callWithSyncFee request

Body

application/json

taskIdstring

Request

JavaScriptCurlPython

const response = await fetch('/relays/v2/call-with-sync-fee', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "chainId": 0,
      "target": "text",
      "data": "text",
      "feeToken": "text"
    }),
});
const data = await response.json();

Response

201

{
  "taskId": "text"
}

/call-with-sync-fee-erc2771/: for more information, please click here.

Place a relay v2 callWithSyncFeeERC2771 request

Please find more information here: https://docs.gelato.network/developer-products/gelato-relay-sdk/sdk-methods/relaywithsyncfeeERC2771

POST/relays/v2/call-with-sync-fee-erc2771

Body

application/json

chainId*number

target*string

data*string

user*string

userNonce*number

userDeadline*number

userSignature*string

feeToken*string

isRelayContextboolean

sponsorApiKeystring

gasLimitstring

retriesnumber

Response

201400404

Successfully placed a callWithSyncFeeERC2771 request

Body

application/json

taskIdstring

Request

JavaScriptCurlPython

const response = await fetch('/relays/v2/call-with-sync-fee-erc2771', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "chainId": 0,
      "target": "text",
      "data": "text",
      "user": "text",
      "userNonce": 0,
      "userDeadline": 0,
      "userSignature": "text",
      "feeToken": "text"
    }),
});
const data = await response.json();

Response

201

{
  "taskId": "text"
}

/sponsored-call/: for more information, please click here.

Place a relay v2 sponsoredCall request

Please find more information here: https://docs.gelato.network/developer-products/gelato-relay-sdk/sdk-methods/relaywithsponsoredcall

POST/relays/v2/sponsored-call

Body

application/json

chainId*number

target*string

data*string

sponsorApiKey*string

gasLimitstring

retriesnumber

Response

201400404

Successfully placed a sponsoredCall relay request

Body

application/json

taskIdstring

Request

JavaScriptCurlPython

const response = await fetch('/relays/v2/sponsored-call', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "chainId": 0,
      "target": "text",
      "data": "text",
      "sponsorApiKey": "text"
    }),
});
const data = await response.json();

Response

201

{
  "taskId": "text"
}

/sponsored-call-erc2771/: for more information, please click here.

Place a relay v2 sponsoredCallERC2771 request

Please find more information here: https://docs.gelato.network/developer-products/gelato-relay-sdk/sdk-methods/relaywithsponsoreduserauthcall

POST/relays/v2/sponsored-call-erc2771

Body

application/json

chainId*number

target*string

data*string

user*string

userNonce*number

userDeadline*number

userSignature*string

sponsorApiKey*string

gasLimitstring

retriesnumber

Response

201400404

Successfully placed a sponsoredCallERC2771 relay request

Body

application/json

taskIdstring

Request

JavaScriptCurlPython

const response = await fetch('/relays/v2/sponsored-call-erc2771', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "chainId": 0,
      "target": "text",
      "data": "text",
      "user": "text",
      "userNonce": 0,
      "userDeadline": 0,
      "userSignature": "text",
      "sponsorApiKey": "text"
    }),
});
const data = await response.json();

Response

201

{
  "taskId": "text"
}

Task Tracking

Get task status of the relay v2 task id

GET/tasks/status/{taskId}

Path parameters

taskId*string

Id of the task whose status is retrieved

Response

200404500

Successful Retrieval

Body

application/json

taskTaskStatus (object)

Request

JavaScriptCurlPython

const response = await fetch('/tasks/status/{taskId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "task": {
    "chainId": 0,
    "taskId": "text",
    "taskState": "CheckPending",
    "creationDate": "text",
    "lastCheckDate": "text",
    "lastCheckMessage": "text",
    "transactionHash": "text",
    "executionDate": "text",
    "blockNumber": 0
  }
}

Debug Endpoint

Retrieve debug information for a specific task

GEThttps://api.gelato.digital/tasks/status/{taskId}/debug

Path parameters

taskId*string

The ID of the task to retrieve debug information for.

Query parameters

Response

200400404

Successful response with debug information.

Body

application/json

dataobject

debuggerobject

Request

JavaScriptCurlPython

const response = await fetch('https://api.gelato.digital/tasks/status/{taskId}/debug?tenderlyUsername=text&tenderlyProjectName=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "data": {
    "to": "text",
    "from": "text",
    "calldata": "text",
    "blockNumber": 0,
    "gasLimit": 0,
    "chainId": 0,
    "taskId": "text"
  },
  "debugger": {
    "tenderly": "text"
  }
}

How to use it with Tenderly

If you'd like to use the debug endpoint with tenderly, you can make use of the debug endpoint and by adding the following parameters

• tenderlyUsername

• tenderlyProjectName

the request URL should look like this: https://api.gelato.digital/tasks/status/{yourRelayTaskId}/debug?tenderlyUsername={yourUserName}&tenderlyProjectName={yourProjectName}

Everything will already be pre-set, all you need to do is click on "Simulate" and check what might have been the point of failure:

What to do if the calldata is too big?

If the calldata is too big which may result in the following error upon clicking on the url returned by the api response:

In this case you would have to manually copy and paste the to, from, callData, blockNumber etc into the Tenderly UI or Foundry