Oracle

The Oracle Decompiler API provides a powerful service for decompiling Lua scripts. This guide explains how to use the API effectively.

Authentication

All API requests require authentication using a Bearer token. Include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY

Endpoint

POST https://oracle.mshq.dev/decompile

Request Format

The API accepts POST requests with a JSON body containing the following parameters:

Parameter	Type	Description
script	string	Base64 encoded bytecode of the Lua script
decompilerOptions	object	(Optional) Configuration options for the decompiler

Decompiler Options

Option	Type	Description
renamingType	string	Type of renaming to apply ("NONE", "UNIQUE", "UNIQUE_VALUE_BASED")
removeDotZero	boolean	Remove .0 from numbers
removeFunctionEntryNote	boolean	Remove function entry notes
swapConstantPosition	boolean	Swap constant positions in expressions
inlineWhileConditions	boolean	Inline while loop conditions
showFunctionLineDefined	boolean	Show line numbers where functions are defined
removeUselessNumericForStep	boolean	Remove unnecessary step values in numeric for loops
removeUselessReturnInFunction	boolean	Remove redundant return statements at function end
sugarRecursiveLocalFunctions	boolean	Optimize recursive local function declarations
sugarLocalFunctions	boolean	Optimize local function declarations
sugarGlobalFunctions	boolean	Optimize global function declarations
sugarGenericFor	boolean	Optimize generic for loop syntax
showFunctionDebugName	boolean	Show debug names for functions
upvalueComment	boolean	Add comments for upvalue references

Response Codes

Status Code	Description
200	Success - Returns decompiled code
400	Bad Request - Invalid options or script format
401	Unauthorized - Invalid API key
402	Payment Required - Insufficient tokens
429	Too Many Requests - Rate limit exceeded
500	Server Error - Decompilation failed

Example Usage (Node.js)

const key = "YOUR_API_KEY";
var https = require('https');
var fs = require('fs');

function request(script, key) {
    return new Promise((resolve, reject) => {
        const encoded = script.toString('base64');
        const post_data = JSON.stringify({
            'script': encoded
        });

        const post_options = {
            host: 'oracle.mshq.dev',
            path: '/decompile',
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Content-Length': Buffer.byteLength(post_data, 'utf8'),
                'Authorization': 'Bearer ' + key
            }
        };

        const post_req = https.request(post_options, (res) => {
            let data = '';

            res.setEncoding('utf8');
            res.on('data', (chunk) => {
                data += chunk;
            });

            res.on('end', () => {
                if (res.statusCode === 200) {
                    resolve(data.toString('utf8'));
                } else if (res.statusCode === 402) {
                    resolve(data.toString('utf8'));
                } else if (res.statusCode === 429) {
                    resolve(data.toString('utf8'));
                } else if (res.statusCode === 500) {
                    reject('-- Decompilation failed!');
                } else if (res.statusCode === 400) {
                    reject('-- Update the decompiling script');
                } else {
                    reject(`-- Something went wrong when decompiling: ${res.statusCode}`);
                }
            });
        });

        post_req.on('error', (e) => {
            reject(`-- Request failed: ${e.message}`);
        });

        post_req.write(post_data);
        post_req.end();
    });
}

Example Usage (Lua)

local key = "YOUR_API_KEY"
local options = {
    renamingType = "UNIQUE",
    removeDotZero = true,
    sugarGenericFor = true
}

function decompile(s)
    local response = request {
        Url = "https://oracle.mshq.dev/decompile?key=" .. key,
        Method = "POST",
        Headers = {
            ["Content-Type"] = "application/json"
        },
        Body = json.encode({
            script = encode(getscriptbytecode(s)),
            decompilerOptions = options
        }),
    }

    return
        response.StatusCode == 200 and response.Body or
        response.StatusCode == 402 and response.Body or
        response.StatusCode == 429 and response.Body or
        response.StatusCode == 401 and response.Body or
        response.StatusCode == 500 and "-- Decompilation failed!" or
        response.StatusCode == 400 and "-- Update the decompiling script / Check decompiling options for errors" or
        "-- Something went wrong when decompiling: " .. response.StatusCode
end

Rate Limits

The Decompiler API uses a queue-based rate limiting system:

Requests are processed as they are uploaded in a queue system
Processing time depends on script complexity and current queue length

Note: You may get rate limited if you send too many requests in a short period of time.

Documentation

Decompiler API