Web Access

Web Access lets Intelligent Contracts fetch external data, send HTTP requests, render web pages, capture screenshots, and handle API errors from non-deterministic blocks. Because leaders and validators make independent web requests, use stable fields or derived summaries when applying the Equivalence Principle to web data.

HTTP Requests

Send data to external services:

def post_request():
    url = "https://test-server.genlayer.com/body/echo"
    response = gl.nondet.web.request(
        url,
        method='POST',
        body={}
    )
    return response.status
 
status_code = gl.eq_principle.strict_eq(post_request)

The response exposes the HTTP status, headers, and body returned to the contract.

Web Rendering

Render web page and extract content:

def render_page():
    url = "https://test-server.genlayer.com/static/genvm/hello.html"
    # Render HTML content
    html_content = gl.nondet.web.render(url, mode='html')
    return html_content
 
page_html = gl.eq_principle.strict_eq(render_page)

Screenshot Capture

Take screenshots of web pages:

def take_screenshot():
    url = "https://test-server.genlayer.com/static/genvm/hello.html"
    # Capture page as image
    screenshot = gl.nondet.web.render(url, mode='screenshot')
    return screenshot
 
image_data = gl.eq_principle.strict_eq(take_screenshot)

Handling HTTP Errors

External APIs can return error responses. Consider checking the status code:

def fetch_data():
    response = gl.nondet.web.request(api_url, method='GET')
    if response.status >= 400 and response.status < 500:
        raise gl.UserError(f"API returned client error: {response.status}")
    elif response.status >= 500:
        raise gl.UserError(f"API temporarily unavailable: {response.status}")
    return json.loads(response.body.decode("utf-8"))

Redirects and evidence origin

gl.nondet.web.request() may follow HTTP redirects before returning the response body. Today, the response object does not expose the final or effective URL, and the request API does not provide a switch to disable redirects.

That means an allowlist check on the requested URL is not, by itself, proof that the response body came from that same host. If your contract depends on the origin of external evidence, prefer sources that provide one of these guarantees:

a canonical API endpoint that does not redirect across origins;
signed or verifiable payloads that include the source identity;
response fields whose issuer or origin can be validated in the payload itself; or
an application-level check against trusted metadata returned by the source.

Avoid treating the requested host as sufficient evidence-origin verification when redirects could change where the data is fetched from.

Consensus-Friendly Web Requests

When using web data in non-deterministic blocks, remember that the leader and validators make independent requests. External APIs may return different data between calls — timestamps change, counts update, caches vary.

Extract Stable Fields

One approach is to return only the fields that won't change between calls:

def leader_fn():
    res = gl.nondet.web.get(api_url)
    data = json.loads(res.body.decode("utf-8"))
    # Only return fields that are stable across requests
    return {"id": data["id"], "login": data["login"], "status": data["status"]}
    # NOT: follower_count, updated_at, online_status

Derive Status from Variable Data

When raw data may differ between leader and validator (e.g., CI check counts change), consider comparing a derived summary instead of the raw values:

def validator_fn(leaders_res: gl.vm.Result) -> bool:
    validator_data = leader_fn()
 
    def derive_status(checks):
        if not checks:
            return "pending"
        for c in checks:
            if c.get("conclusion") != "success":
                return "failing"
        return "success"
 
    return derive_status(leaders_res.calldata) == derive_status(validator_data)

See the Equivalence Principle page for more validation patterns.

Image Processing Balances