# REST API

## Your First Requests

Once you have your API key and Oracle Program ID, you can make your first request to SEDA FAST.

**Basic Example (cURL):**

```bash
curl -X GET "https://fast-api.seda.xyz/execute?execProgramId=YOUR_PROGRAM_ID&execInputs=YOUR_INPUTS" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

{% hint style="info" %}
By default inputs prefixed with `0x` are treated as hexadecimal and inputs without `0x` are directly passed as a UTF-8 string. See [API reference](broken://pages/bAxEG5TXsOZGxOs5NT6L#get-execute) for more details.
{% endhint %}

**Javascript Example:**

```jsx
const response = await fetch(
  'https://fast-api.seda.xyz/execute?execProgramId=YOUR_PROGRAM_ID&execInputs=YOUR_INPUTS',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(data);
```

{% hint style="info" %}
The `/execute` endpoint supports both GET (with query parameters) and POST (JSON body). For more complex inputs we recommend POST.
{% endhint %}

### Understanding the Response

A successful execution returns a JSON response structured as follows:

```json
{
  "_tag": "ExecuteResponse",
  "data": {
    "id": "4662b513-d7a1-4eb0-b6aa-7164a5e863e0",
    "dataRequest": {
      "consensusFilter": "00",
      "execGasLimit": "300000000000000",
      "execInputs": "35343738322d3239",
      "execProgramId": "85975ef3a54e8db6b017a75b4027e14277a1518337ec00e353c8e2bf6d2b4556",
      "gasPrice": "0",
      "memo": "",
      "replicationFactor": 1,
      "tallyGasLimit": "50000000000000",
      "tallyInputs": "",
      "tallyProgramId": "85975ef3a54e8db6b017a75b4027e14277a1518337ec00e353c8e2bf6d2b4556",
      "version": "0.0.1"
    },
    "dataResult": {
      "drId": "d5306d2c64366db786dd03a6e73f694c36a6c076ec21670b7c5f8e6c4532a12c",
      "gasUsed": "29136976762500",
      "blockHeight": "0",
      "blockTimestamp": "1761675002786",
      "consensus": true,
      "exitCode": 0,
      "version": "0.0.1",
      "result": "000000000000000000000000000000000000000000000000000000000007564d",
      "paybackAddress": "",
      "sedaPayload": ""
    },
    "signature": "bf508ac6a8d3d5ed0034cfaa607253eb49a2a616c276cf402e1bc897b6b1edb63f59cb5481c5891bd7d867942499e6b9117b957267d5ceb0726e57e12d29b99200",
    "result": "0x000000000000000000000000000000000000000000000000000000000007564d"
  }
}
```

**Key fields:**

* `id` - Unique identifier for this execution request
* `dataRequest` - Details of the Oracle Program execution request (program IDs, inputs, gas limits)
* `dataResult.result` - The hex-encoded final result from the Oracle Program
* `dataResult.exitCode` - 0 indicates success, non-zero indicates an error
* `dataResult.gasUsed` - Total gas consumed during execution
* `dataResult.drId` - Unique identifier for this data request
* `signature` - Cryptographic signature produced by the FAST service.
* `result` - Convenient top-level access to the result (same as dataResult.result)

{% hint style="info" %}
Additional fields may be included in the response depending on the query parameters used. See the [API Reference](broken://pages/5HFUqqa9AIs1OMqX7Icl) for complete details on all available parameters and response fields.
{% endhint %}

### Basic Error Handling

SEDA FAST uses standard HTTP status codes to indicate success or failure. Always check the response status before processing the data. Common error codes include insufficient credits (403), invalid API keys (401), and program execution failures (599).

**Javascript example:**

```jsx
const response = await fetch(url, { headers });

if (!response.ok) {
  switch (response.status) {
    case 401:
      console.error('Invalid API key');
      break;
    case 403:
      console.error('Insufficient credits');
      break;
    case 404:
      console.error('Oracle Program not found');
      break;
    case 429:
      console.error('Credit limit exceeded');
      break;
    case 599:
      console.error('Oracle Program execution failed');
      break;
    default:
      console.error('Request failed:', response.status);
  }
  return;
}

const data = await response.json();

// Check execution result
if (data.data.dataResult.exitCode !== 0) {
  console.error('Oracle Program execution failed');
  // Check data.data.execute.stderr for error details
}
```

The error code `599` is a special case. The request succeeded, but the oracle program ran into a problem during execution and exited with a non-zero exit code. When debugging these failures, the response can include additional fields like "stderr" and "stdout" to help identify the issue (use the `includeDebugInfo` parameter to enable these).

For a complete list of error codes and their meanings, see the Error Codes section in the [REST API Reference](broken://pages/bAxEG5TXsOZGxOs5NT6L).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.seda.xyz/home/developer/developer-tools/rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.