The Arkena backend exposes a REST API at https://api.arkena.io (with a
same-origin proxy from arkena.io itself for browser-based dApps). This
page describes the API by capability — the surface most dApps reach for
in the first week.
A full per-endpoint reference, generated from OpenAPI, is in development. Until it ships, this overview plus the route table on the running server is the canonical source.
Authentication
Most endpoints require a SIWC JWT attached as Authorization: Bearer <token>.
Public read endpoints (collection listings, NFT detail) don't require a
token. See Sign-In with Canton.
| Endpoint | Purpose |
|---|---|
POST /api/auth/nonce | Issue a structured message to sign |
POST /api/auth/verify | Verify the signature, issue a JWT |
GET /api/auth/me | Return the partyId attached to the current JWT |
POST /api/auth/logout | Invalidate the current JWT |
NFT category
Read and modify NFT state. All write paths follow prepare/execute. NFT operations flagged "atomic" use a single signed action that fans out into multiple on-chain effects (e.g. price + ownership + fee splits all in one step).
| Endpoint | Purpose |
|---|---|
GET /api/nft/collections | Paginated list of collections |
GET /api/nft/slug/{slug} | Collection by slug |
GET /api/nft/collection/{id}/nfts | NFTs in a collection (paginated, filterable) |
GET /api/nft/token/{contractId} | NFT detail with traits and history |
POST /api/nft/mint/atomic/prepare + /execute | Mint from an active phase |
POST /api/nft/mint/batch/atomic/prepare + /execute | Batch mint (multiple items in one signature) |
POST /api/nft/list/prepare + /execute | List for sale |
POST /api/nft/list/{cid}/cancel/prepare + /api/nft/list/cancel/execute | Cancel a listing |
POST /api/nft/list/batch/atomic/prepare + /execute | List many in one signature |
POST /api/nft/listing/batch/cancel/prepare + /execute | Cancel many listings in one signature |
POST /api/nft/buy/atomic/prepare + /execute | Buy a listed NFT (atomic settlement) |
POST /api/nft/sweep/buy/prepare + /execute | Multi-item sweep across a collection |
POST /api/nft/transfer/prepare + /execute | Direct transfer |
POST /api/nft/burn/prepare + /execute | Burn |
Example — fetch collections:
curl https://api.arkena.io/api/nft/collectionsSwap category
Submit, cancel, and observe swap intents. Pool aggregates and history queries live here too.
| Endpoint | Purpose |
|---|---|
GET /api/swap/quote | Indicative quote (oracle-priced, non-binding) |
POST /api/swap/prepare | Prepare a swap intent |
POST /api/swap/intent/submit | Submit the signed intent |
POST /api/swap/intent/cancel/prepare + /execute | Cancel a pending intent |
GET /api/swap/intent/status?intentCid={cid} | Status polling |
GET /api/swap/intent/active?taker={party} | List the user's open intents |
GET /api/swap/pool/{poolId} | Pool detail |
GET /api/swap/pool/{poolId}/aggregates | TVL, LP count, accrued fees, depth-weighted spread |
GET /api/swap/pool/{poolId}/outcomes | Recent swap receipts on this pool |
GET /api/swap/history?taker={party} | The user's swap history |
GET /api/swap/pool/{poolId}/history | Per-pool swap history |
LP quotes
| Endpoint | Purpose |
|---|---|
POST /api/swap/lp-quote/prepare + /execute | Publish an LP quote |
POST /api/swap/lp-quote/cancel/prepare + /execute | Cancel an LP quote |
GET /api/swap/lp-quote/active?lp={party} | List the LP's active quotes |
POST /api/swap/lp-quote/claim-fees/prepare + /execute | Claim accrued fees |
Wallet category
Read and write user-scoped state.
| Endpoint | Purpose |
|---|---|
GET /api/wallet/balance/{partyId} | Multi-token balance (CC + USDCx) |
GET /api/wallet/utxo-count/{partyId} | UTXO fragmentation telemetry |
POST /api/wallet/cc-transfer/prepare + /execute | CC transfer |
POST /api/wallet/nft-preapproval/prepare + /execute | One-time consent to receive NFTs |
POST /api/wallet/usdcx-preapproval/prepare + /execute | One-time consent to receive USDCx |
POST /api/wallet/preapproval/renew | Renew an existing receive-preapproval |
GET /api/wallet/rewards/{partyId} | Reward balance |
GET /api/wallet/rewards/{partyId}/history | Reward history |
Pagination, errors, rate limits
Pagination. Most list endpoints use cursor-based pagination. Each
response includes a cursor field; pass it as ?cursor=... on the next
call. Page size defaults to 20.
Errors. Uniform JSON shape, full table in Error codes.
Rate limits. Default 300 requests per minute per origin for read
endpoints; 60 per minute for prepare endpoints. Hit the limit and you'll
get 429 with a Retry-After header.
What's next
- Sign and submit transactions — the prepare/execute calls in code.
- Error codes — error semantics.
- Connect Button recipe — a complete component using this API.