# REST API Reference

This section provides detailed documentation for all SEDA FAST API endpoints. For interactive API exploration and testing, refer to the OpenAPI documentation links below:

* Testnet: <https://fast-api.testnet.seda.xyz/docs>
* Mainnet: <https://fast-api.mainnet.seda.xyz/docs>

## Base URLs

SEDA FAST is available on the following networks:

* **Testnet**: <https://fast-api.testnet.seda.xyz>
* **Mainnet**: [https://fast-api.mainnet.seda.xyz](https://fast-api.mainnet.seda.xyz/)

## Authentication

All API requests (except `/health` and `/info`) require authentication using a bearer token in the Authorization header:

```jsx
Authorization: Bearer YOUR_API_KEY
```

Your API key is provided during onboarding and is specific to your account. Keep it secure and never expose it in client-side code or public repositories.

## Endpoints

SEDA FAST provides several endpoints for executing Oracle Programs, managing your account, and monitoring service health. The primary endpoint is `/execute`, which handles all Oracle Program executions.

<table><thead><tr><th width="120.1328125">Method</th><th width="246.02734375">Path</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td><a href="#get-execute"><code>/execute</code></a></td><td>Execute an Oracle Program</td></tr><tr><td>POST</td><td><a href="#post-execute"><code>/execute</code></a></td><td>Execute an Oracle Program</td></tr><tr><td>GET</td><td><a href="#get-execute-last-result"><code>/execute/last-result</code></a></td><td>Retrieve the last result of the execution</td></tr><tr><td>POST</td><td><a href="#post-execute"><code>/execute/last-result</code></a></td><td>Retrieve the last result of the execution</td></tr><tr><td>GET</td><td><a href="#get-project"><code>/project</code></a></td><td>Retrieve your project configuration</td></tr><tr><td>GET</td><td><a href="#get-info"><code>/info</code></a></td><td>FAST public key and version information</td></tr><tr><td>GET</td><td><a href="#get-data-request-reports"><code>/data-request-reports</code></a></td><td>Retrieve historical execution reports</td></tr><tr><td>GET</td><td><a href="#get-data-proxy-public_key"><code>/data-proxy/{public_key}</code></a></td><td>Check FAST information for a data proxy</td></tr><tr><td>GET</td><td><a href="#get-verify"><code>/verify</code></a></td><td>Verify the authentication header</td></tr></tbody></table>

#### **GET `/execute`**

Execute an Oracle Program and return the result.

**Required Parameters:**

* `execProgramId` - Oracle Program ID deployed on SEDA chain (hex string)

**Optional Parameters:**

* `execInputs` / `tallyInputs` - Inputs for execution/tally phases (hex or UTF-8 string)
* `tallyProgramId` - Separate tally program (defaults to execProgramId)
* `inputEncoding` - The encoding of the execution and tally input parameters. Defaults to `auto`
  * `auto` - Auto-detect based on 0x prefix. Strings starting with 0x are treated as hex, others as UTF-8.
  * `hex` - Always treat input as a hex string (0x prefix is stripped if present).
  * `utf8` - Always treat input as UTF-8 text, even if it starts with 0x (useful for passing contract addresses as strings).
  * `base64` - Decode input from base64.
* `returnLastResult` - Return cached result for ultra-low latency
* `includeSummary` - Include credit usage details in response
* `includeDebugInfo` - Include stdout/stderr for debugging
* `encoding` - Output format for the `result` field: `hex`, `base64`, or `utf8`

**Execute Request Example:**

```bash
curl -X GET 'https://fast-api.seda.xyz/execute?execProgramId=85975ef3a54e8db6b017a75b4027e14277a1518337ec00e353c8e2bf6d2b4556&execInputs=54782d29' \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"
```

**Response:** Returns execution result with signature, gas usage, and exit code. Status 200 for success, 599 for failed execution (non-zero exit code). A common cause for 599 is that a HTTP request from the execution phase failed or timed out.

#### POST `/execute`&#x20;

Similar to [#get-execute](#get-execute "mention"), but takes the program IDs and inputs as a JSON body:

```shellscript
curl -L -X POST 'https://fast-api.mainnet.seda.xyz/execute?encoding=utf8&includeDebugInfo=true' \
-H 'Authorization: Bearer {{BEARER_TOKEN}}' \
-H 'Content-Type: application/json' \
--data-raw '{
    "execProgramId": "85975ef3a54e8db6b017a75b4027e14277a1518337ec00e353c8e2bf6d2b4556",
    "execInputs": {
        "complex": {
          "objects": "are supported"
        },
        "list": [1, 2, 3] 
    }
}'
```

Just like the GET call only the `execProgramId` is required, `execInputs`, `tallyProgramId`, and `tallyInputs` are optional.

**Optional Query Parameters:**

* `returnLastResult` - Return cached result for ultra-low latency
* `includeSummary` - Include credit usage details in response
* `includeDebugInfo` - Include stdout/stderr for debugging
* `encoding` - Output format for the `result` field: `hex`, `base64`, or `utf8`

#### **GET `/execute/last-result`**

Returns the last stored result of the execution. Uses the same parameters as the GET `/execute` call with 1 additional parameter.

**Optional Query Parameters:**

* `mode` - Either `success` to retrieve that last successful result, of `last` to retrieve the last result regardless of success. Defaults to `last`

#### POST `/execute/last-result`

Returns the last stored result of the execution. Uses the same parameters and JSON body as the POST `/execute` call with 1 additional parameter.

**Optional Query Parameters:**

* `mode` - Either `success` to retrieve that last successful result, of `last` to retrieve the last result regardless of success. Defaults to `last`

#### **GET `/project`**

Retrieve your project configuration, including credits, limits, and allow-lists.

**Parameters:** None

**Response:** Current credit balance, usage limits, gas limits, and Oracle Program allow-list configuration.

#### **GET `/data-request-reports`**

Query historical execution reports for your project.

**Required Parameters:**

* `drId` - The identifier of a data request; returned by the execute endpoints. Identifies a combination of execProgramId+execInputs+tallyProgramId+tallyInputs.

**Optional Parameters:**

* `startDate` / `endDate` - Filter by date range
* `amount` - Number of reports to return (1-100, default: 25)
* `nextPageId` - Pagination cursor as returned by a previous call

**Response:** Paginated list of past executions with results and metadata.

#### **GET `/info`**

Get SEDA FAST public key and version information.

**Parameters:** None

**Authentication:** Not required

**Response:** Public key (for signature verification) and API version.

#### **GET `/health`**

Health check endpoint for monitoring.

**Parameters:** None

**Authentication:** Not required

**Response:** Service status.

#### GET `/data-proxy/{public_key}`

Check FAST information for a data proxy by providing the hex encoded public key.

**Required Path Parameters**

* `{public_key}` - The hex encoded public key of the data proxy, e.g. `02088452cd5025f33d7ce95ee8eb7ba34b94b518ea23b1897665e1afdbcae2ca18`

**Authentication:** Not required

**Response:**

```json
{
  "registered": true,
  "name": "data-proxy",
  "publicKey": "02088452cd5025f33d7ce95ee8eb7ba34b94b518ea23b1897665e1afdbcae2ca18",
  "fee": "0"
}
```

#### GET `/verify`&#x20;

Verify the API key and retrieve basic information.

```json
{
  "apiKeyId": "0000000",
  "apiKeyExpiresAt": null,
  "organizationId": "00000000-0000-0000-0000-00000000000",
  "organizationSlug": "seda",
  "remainingCreditsSnapshot": "1000000000000000000000000",
  "projectId": "00000000-0000-0000-0000-00000000000",
  "usedCreditsSnapshot": "0"
}
```

## Error Codes

| Status | Description                                   |
| ------ | --------------------------------------------- |
| 200    | Success                                       |
| 400    | Invalid or disallowed parameters              |
| 401    | Invalid/missing API key                       |
| 403    | Insufficient credits                          |
| 404    | Oracle Program not found                      |
| 429    | Credit limit exceeded                         |
| 500    | Server error                                  |
| 599    | Program execution failed (non-zero exit code) |

{% hint style="info" %}
Use query parameter `includeDebugInfo=true` on `/execute` to get stdout/stderr for debugging failed executions.
{% endhint %}


---

# 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/rest-api-reference.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.