JAVASCRIPT SDKv0.3.38

API reference.

Try it first

Look up one operation before implementing it#

You need A known task and the matching API host and test credentials.

Find the endpoint’s method, authentication and required identifiers.
Compare its response with a real test request.
Follow the lifecycle guide for retry and fulfillment behavior.

Check your result You know which fields are authoritative and how to recover that operation.

SDK methods call the versioned Playmos service. Use the SDK for typed inputs, retries and payment flow orchestration.

API origins#

Environment	Origin
Test / Base Sepolia	`https://api.sandbox.playmos.io/v1`
Live / Base	`https://api.playmos.io/v1` — capability and production approval required

Authenticate with Authorization: Bearer <key>. The key prefix selects the environment. Explicit network overrides must agree.

Core endpoints#

POST/v1/payments

pay() / enterRound()

Create an IAP or entry intent. Explicit server settlement is test-only.

GET/v1/payments/:id

verify(id)

Studio-scoped payment read with verification provenance.

POST/v1/payments/:id/tx

SDK-managed

Report a transaction for verification; reporting is not confirmation.

GET/v1/payments

Server API · sk_ required

Filter studio payments; capped cached listing, not a complete ledger.

GET/v1/rounds/:id

rounds.getWithMeta()

Read round state and chain-read metadata.

POST/v1/epochs/pools/prepare

epochs.preparePool()

Prepare an unsigned studio pool transaction.

GET/v1/epochs/:epochId

epochs.get()

Read the relevant epoch using its pool and series context.

GET/v1/webhook_endpoints

Server API · sk_ required

Inspect studio-owned endpoint registrations and recorded attempts.

GET/v1/health

Service diagnostics

Capability, chain-read and sandbox signer readiness. Global health is not per-studio analytics.

Languages and package support

Studio setup and webhook API#

Method / path	Purpose
POST /v1/keys	Self-serve test studio/key issuance; live keys remain gated.
POST /v1/studio/payout	Set payout wallet with your server secret.
GET /v1/keys/me · POST /v1/keys/revoke	Inspect or revoke studio credentials.
POST /v1/webhook_endpoints	Register endpoint and return its signing secret.
GET /v1/webhook_endpoints	Inspect registration and recorded attempts; no secret readback.

Contest API#

Method / path	Contract
POST /v1/rounds · POST /v1/rounds/:id/lock · POST /v1/rounds/:id/settle	Legacy operator lifecycle; sk_ required. Not studio EpochPrizePool.
POST /v1/rounds/:id/cancel	Legacy cancellation; reconcile its terminal state.
GET /v1/rounds/:id/payout-notices · POST /v1/rounds/:id/push-winnings	Legacy notices and operator push; see payout states.
POST /v1/epochs/pools/prepare · POST /v1/epochs/pools	Unsigned pool prepare, then ownership registration.
GET /v1/epochs/pools	Studio pool listing.
POST /v1/epochs/series/prepare · GET /v1/epochs/series	Prepare unsigned series; read actual creation state.
GET /v1/epochs/current · GET /v1/epochs/current/prize	Current window and prize, scoped by pool/series.
POST /v1/epochs/enter · POST /v1/epochs/enter/confirm	SDK entry plan and mined-event confirmation.
GET /v1/epochs/:epochId · GET /v1/epochs/:epochId/prize	Past/current window and player prize reads.
POST /v1/epochs/:epochId/settle/signed	Server relay of studio operator-signed results; sk_ and configured relay required.
GET /v1/epochs/:epochId/attestation	Read the available signed winner payload.

epochs.executeSettlement, withdraw and refund pulls in SDK 0.3.38 send through the client’s wallet. They do not call the similarly named service relay route. Preserve pool, series, epoch and chain context on every read and send.

Economy, HTTP and payout API#

Method / path	Purpose
POST /v1/agents/wallets · GET /v1/agents/wallets/:agentId	Server-owned agent wallet creation/read.
POST /v1/agents/wallets/:agentId/fund	Sandbox test fixture funding.
POST /v1/transfers · GET /v1/transfers/:id	Transfer and same-ID reconciliation.
POST /v1/x402/challenges · POST /v1/x402/settle	Service-minted challenge and fulfillment.
POST /v1/payouts/mode · POST /v1/payouts/onboarding_link	Payout configuration surfaces; fiat onboarding is a stub.

If it did not work#

A listed endpoint is not a complete integration. Check studio ownership, host and release availability when a route is absent.

Try one variation Find the same operation’s recovery guide. Explain which failures allow a retry and which need a read first.

Continue with the next guide →