Quickstart

Step 1. Sign up and create a project

Create an account, then an organization and a project. Payments, balances and API keys all live at the project level, so one project keeps its own books separate from the next.

Sign up takes you straight into your dashboard, where you manage projects, API keys, payments and balances.

Step 2. Create an API key

Inside your project, create a v2 API key. You pass it in the X-Api-Key header on every server-to-server call. Keys carry their own rate limit and can be rotated, and you revoke one by its prefix.

Suward authenticates two ways: a cookie session (HttpOnly accessToken and refreshToken) for the browser dashboard, and the X-Api-Key header for server integration. Keep the key on your backend and never ship it to the browser.

Step 3. Create a payment

One payment is one asset on one network. Send the amount, the asset, an optional externalId (your order reference) and a callbackUrl. The response hands back a unique deposit address for this payment alone.

Pass your own externalId as the order key. Send the same externalId again and Suward returns the existing payment instead of opening a second one, so a retried request never double-counts an order. Money values are strings, not floats. A single payment caps at 60,000.

1curl -X POST https://api.suward.com/v1/projects/{projectId}/payments \
2  -H "X-Api-Key: <API_KEY>" \
3  -H "Content-Type: application/json" \
4  -d '{"amount":"100.00","asset":"USDT","externalId":"order-42","isTest":false}'

Step 4. Show the checkout

Two ways to collect the payment. Redirect the buyer to the hosted Suward page, which shows the QR address, a watching-mempool indicator and a countdown. Or render your own UI from the address, amount and asset and monitor the status yourself.

There is no embeddable widget or JS SDK yet, only the hosted redirect. The hosted checkout URL is included in the payment response.

Step 5. Check payment status

Poll the payment until it reaches a terminal status. The status comes in two levels: status (the top line, e.g. PENDING, ACCEPTED, SUCCESS, FAILED) and subStatus (the on-chain detail: Pending → Safe → Finalized). The public GET /v1/payments/{paymentId} suits a checkout page; the project-scoped path returns the full picture.

Read status names dynamically from GET /v1/paymentStatuses rather than hardcoding them, so your integration survives a future status change.

1# Public endpoint — no auth needed for the checkout page
2curl https://api.suward.com/v1/payments/{paymentId}

Step 6. Read your balance

After a payment reaches SUCCESS, the amount is credited to your project balance. Balances are split into safe and accepted, stored as Decimal128, and never go negative.

1curl https://api.suward.com/v1/projects/{projectId}/balances \
2  -H "X-Api-Key: <API_KEY>"