WebSorobandocs v1
Open IDE

reference

API reference

The public WebSoroban backend endpoints, request bodies, responses, and which ones sign with your wallet.

Every endpoint is under the base path /api and requires a Bearer token unless marked otherwise. All operations run against the Stellar testnet, mainnet is never used.

Reading the badges

read-only never signs. signed signs with your testnet wallet and pays a fee. queued returns a jobId; poll the job for the result.

Compile#

POST /api/compile#

queued

Queue a build of a project to Wasm. Does not sign. Unlimited on every plan.

projectIdstringrequired
The project to compile.
filesobjectrequired
The project's files to materialize in the build container.
successboolean
true when the job is queued (HTTP 202).
jobIdstring
Id of the compile job to poll.
logsarray
Initial status log entries.

Deploy#

POST /api/deploy#

signed queued

Queue a deploy: upload the Wasm hash, then instantiate a contract id. The worker signs with your wallet. Counts one deploy against your quota.

projectIdstringrequired
The project to deploy.
wasmBase64stringrequired
The compiled Wasm binary, base64-encoded.
successboolean
true when the job is queued (HTTP 202).
jobIdstring
Id of the deploy job to poll for the contract id.
logsarray
Initial status log entries.

The network is fixed to testnet server-side. Two non-202 cases:

  • Over the plan limit, HTTP 403 with { error, current, limit, upgradeRequired: true }. See Plans and limits.
  • Workspace needs a target, HTTP 400 with { code: "DEPLOY_TARGET_REQUIRED", choices } when the workspace has more than one deployable crate. See Troubleshooting.

Invoke#

GET /api/contracts/:contractId/spec#

read-only

Return the parsed function list used to render the typed Invoke form. Auth is optional.

successboolean
true on success.
contractIdstring
The queried contract id.
functionsarray
Each function with its name, inputs (name + type), and return type.

Returns 404 if no spec is stored or recoverable from chain.

POST /api/contracts/:contractId/invoke#

read-only signed

Invoke a function. Always simulates first. A read returns immediately; a write submits a signed transaction only when execute is true.

functionNamestringrequired
The function to invoke.
argsobject
Arguments keyed by parameter name. Plain values; WebSoroban encodes them to ScVal.
executeboolean
false (default) simulates only. true signs and submits a state-changing call.
clientRefstring
Socket room id for live submitted → pending → confirmed status.
successboolean
true on success, false with a humanized error on failure.
readOnlyboolean
Whether the call was a read (no footprint writes or auth).
statusstring
simulated, submitted, success, or failed.
returnValueany
The decoded return value.
resourceFeestring
The fee in stroops (writes).
txHashstring
The transaction hash (confirmed writes only).
eventsarray
Decoded contract events (confirmed writes).
invocationIdstring
Id of the saved invocation history entry.

Test#

POST /api/test#

queued

Queue cargo test over the project. Does not sign and does not touch the network. Unlimited on every plan.

projectIdstringrequired
The project to test.
filesobjectrequired
The project's files to materialize in the build container.
successboolean
true when the job is queued (HTTP 202).
jobIdstring
Id of the test job to poll for results.
logsarray
Initial status log entries.

POST /api/contracts/:contractId/tests/run#

read-only

Replay the requesting user's saved function tests by simulation and assert each expected return. Counts one function-test run against your quota when at least one test runs.

functionNamestring
Optional. Restrict the run to tests for one function.
successboolean
true on completion.
totalnumber
Number of tests run.
passednumber
Number that passed.
resultsarray
Per-case { testId, name, functionName, status, actual, expected, error }.

Returns 403 with upgradeRequired: true when over the function-test limit. See Plans and limits.

Wallet#

POST /api/wallet/fund#

queued

Top up your testnet wallet from Friendbot if its balance is low. No body.

successboolean
true on success.
publicKeystring
The wallet's public key (G…).
fundedboolean
Whether the wallet is funded after the call.
balancestring
The wallet's testnet XLM balance.

GET /api/wallet/me#

read-only

Return the public details of your server-managed wallet. The secret key is never returned.

successboolean
true on success.
publicKeystring
The wallet's public key (G…).
fundedboolean
Whether the account exists and is funded.
balancestring
The wallet's testnet XLM balance.

Usage#

GET /api/usage#

read-only

Return your current usage and limits, plus recent activity. No body.

successboolean
true on success.
usageobject
deployments and functionTests, each { count, limit, remaining, lastResetDate }. limit is -1 and remaining is "unlimited" on uncapped plans.
statisticsobject
30-day totals (total / successful / failed) for deployments, compilations, and function tests.
logsarray
The most recent usage-log entries.

Next#