Docs

Runrail API Usage

Use the Runrail API to manage the same Execution wallet, jobs, readiness, lifecycle, and execution history that you see in the App.

Create A Credential

Sign in at https://app.runrail.app and open API Access. Create a bearer credential and copy it immediately: the plaintext is shown once and cannot be recovered.

Store the credential in a secret manager or environment variable. Do not commit it, embed it in browser code, put it in a URL, or expose it in logs, screenshots, analytics, debug output, or support messages.

Call The API

The base URL is:

https://api.runrail.app/v1

Send the credential in the Authorization header:

export RUNRAIL_API_CREDENTIAL='replace-with-show-once-credential'

curl --fail --silent --show-error \
  --header "Authorization: Bearer ${RUNRAIL_API_CREDENTIAL}" \
  https://api.runrail.app/v1/account

The API accepts bearer credentials, not App browser sessions. The App accepts its SIWE-derived browser session, not bearer credentials.

Set Up And Read The Execution Wallet

  • GET /execution-wallet reads the wallet lifecycle, address, balance, and readiness that are safe to expose.
  • POST /execution-wallet requests setup and takes no request body.

Fund the resulting address with Base Sepolia test ETH before activating work. Runrail operates the Execution-wallet key; the API never returns it.

Create A Job

Send POST /jobs with an Idempotency-Key header and exactly these five fields:

{
  "name": "hourly-maintenance",
  "target": "0x1111111111111111111111111111111111111111",
  "calldata": "0x",
  "startAt": "REPLACE_WITH_A_FUTURE_UTC_TIMESTAMP",
  "intervalSec": 3600
}

Choose startAt between 2 minutes and 365 days in the future. intervalSec must be between 900 and 31,536,000 seconds. Replace the example target and calldata with the exact Base Sepolia contract call you intend to schedule.

The idempotency key remains active for 24 hours. Repeating the same key with the same normalized request returns the original result without creating another job. Reusing it with a different request returns a conflict.

Inspect And Manage Jobs

  • GET /jobs lists jobs. Add includeArchived=true when you need archived jobs.
  • GET /jobs/{jobId} reads a job and its current readiness.
  • GET /jobs/{jobId}/readiness reads readiness directly.
  • POST /jobs/{jobId}/activate starts future scheduled work after a fresh readiness check.
  • POST /jobs/{jobId}/pause stops future scheduled work.
  • POST /jobs/{jobId}/resume performs a fresh readiness check and continues at a future slot without backfill.
  • POST /jobs/{jobId}/archive irreversibly archives the job while preserving history.

Job and execution-history lists default to 25 items and accept page sizes up to 100. Treat cursors as opaque values returned by Runrail.

Read Execution History

GET /jobs/{jobId}/executions returns scheduled executions and their attempts. Use it to inspect the primary or fallback path, retry, failure, recovery or exhaustion, confirmation, terminal receipt, transaction hash, and Base Sepolia explorer URL.

A submission or transaction hash is not a success result. Use the confirmation and receipt fields to determine the recorded outcome.

Handle Limits And Errors

App sessions and every API credential for one workspace share the same job quotas and request-rate limits. Creating more credentials does not add capacity.

When the API returns 429, wait for the number of seconds in Retry-After. Do not automatically retry a credential-create request with an unclear result; refresh credential metadata in the App, revoke any possible unknown credential, and explicitly create a replacement only if needed.

Credential Lifecycle

The App can list non-secret credential metadata and permanently revoke a credential. Signing out or letting the browser session expire does not revoke API credentials.

You may have at most 3 active credentials and create at most 10 credentials in a rolling 24-hour period. A frozen workspace can list and revoke credentials but cannot create one.

Product Scope

Runrail Public Beta runs on Base Sepolia, chain ID 84532, with user-funded test gas and transaction value=0. Each scheduled slot has one initial attempt and up to two retries.

The API does not provide public run-now, webhooks, caller-defined retry policy, nonzero value, mainnet, multi-chain execution, billing, OAuth, organizations, teams, RBAC, an SDK program, or a developer portal.

Guided Pilot is a separate manual path for custom, out-of-scope, or higher-touch work. It is not required for ordinary API access.

Continue with the Quickstart, App Usage, or Limits and Safety.

Back to docs index