WebSoroban
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. IDE operations (compile, deploy, invoke, test, wallet) run against the Stellar testnet. Payments and PayLoop also run on mainnet when you ask for it explicitly, as described in their sections.

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.

Payments#

GET /api/pay/resource/:slug and /api/pay/live/resource/:slug#

x402 payment

Public hosted resource, on testnet and mainnet respectively. An unpaid request returns HTTP 402, a PAYMENT-REQUIRED header, and a JSON summary containing endpoint, price, asset, and network. Retry with a valid PAYMENT-SIGNATURE to receive the configured JSON response and a PAYMENT-RESPONSE settlement header. A slug requested on the wrong network returns 404 with NETWORK_MISMATCH.

GET /api/pay/networks, /api/pay/wallets, /api/pay/trustline#

read-only

Public. networks lists which networks this server can settle on. wallets lists auth-entry wallet compatibility. trustline?address=&network= reports whether an account can hold USDC (ready, missing_account, missing_trustline, not_authorized, not_applicable, or unknown) with a fix.

GET /api/pay/overview#

read-only

Return Payment Studio metrics, configured endpoints, recent events, settlement success rates (metrics.settlement for 24h, 7d, and 30d), failure reasons with fixes, webhooks with their last delivery, and agent wallets.

POST /api/pay/endpoints#

Create a hosted endpoint. The request accepts name, slug, price, payTo, responseMessage, optional network (stellar:testnet by default, or stellar:pubnet), and optional projectId. The payout address must be able to receive USDC; otherwise the response is 400 PAYOUT_NOT_READY with the trustline report. The response returns the endpoint key once; store it as a server-side secret.

PATCH /api/pay/endpoints/:id#

Pause or resume an endpoint with { "active": boolean }.

POST /api/pay/endpoints/:id/rotate-key#

Invalidate the existing endpoint key and return its replacement once.

Webhooks#

POST /api/pay/webhooks registers a URL for payment.settled, payment.failed, or wallet.spend_limit_exceeded and returns its signing secret once. PATCH /api/pay/webhooks/:id pauses or resumes it, POST /api/pay/webhooks/:id/test sends a signed webhook.test delivery, GET /api/pay/webhooks/:id/deliveries lists recent attempts, and DELETE /api/pay/webhooks/:id removes it.

/api/pay/facilitator/supported, /verify, and /settle#

Endpoint-key-authenticated proxy to the managed x402 facilitator. It accepts only payments to the endpoint's payout address, in USDC, on the endpoint's network, and allows 120 calls per endpoint per minute. Developer credentials are removed before the server adds its own facilitator credentials. See x402 payments for the complete flow.

PayLoop#

Every PayLoop route takes ?network=testnet (default) or ?network=mainnet. A network without a deployed contract returns 404. All routes are public except reconcile. See PayLoop subscriptions.

GET /api/payloop/config#

read-only

Return the network's contract id, USDC token, explorer base, and demo merchant, plus networks (each network and whether it is deployed) and audited (whether the mainnet deployment recorded an independent audit; null when not deployed).

GET /api/payloop/policies#

read-only

List indexed policies, newest first, up to 100. Requires subscriber or merchant; status filters by active, paused, revoked, or completed. Amounts are strings in stroops, with amountUsdc, capUsdc, and spentUsdc alongside.

GET /api/payloop/policies/:policyId#

read-only

One policy and its last 50 charges. Each charge has outcome (charged, insufficient_balance, or insufficient_allowance), txHash, dueAt, and delaySeconds.

GET /api/payloop/stats#

read-only

Policies by status, charge outcomes, and on-schedule metrics (share of recurring charges within a minute of their due time, p50 and p95 lateness).

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#