> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xmonaco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# V0.8.8

# Monaco Protocol SDK v0.8.8

## Breaking: authentication moves to ed25519 session-key signing

Authentication no longer uses JWT access/refresh tokens. The wallet now signs once to authorize a locally-generated ed25519 **session key**, and every request is signed with that key. **All existing sessions are invalidated on deploy — every user must reconnect their wallet and sign once.** Backend and frontend must deploy v0.8.8 together; there is no window where both auth schemes work.

What changes for SDK users:

* `AuthState` no longer has `accessToken` / `refreshToken`. It now carries `sessionPublicKey`, `sessionPrivateKey`, `expiresAt`, and `user`. The **session private key is the credential** — persist it (not a token) to restore a session without re-prompting the wallet.
* `sdk.login(clientId)` is unchanged as the entry point and still returns `AuthState`. Request signing is automatic after login (and after `sdk.setAuthState(...)`); there is no token to attach.
* The manual token methods `sdk.auth.refreshToken(...)` and `sdk.auth.revokeToken()` are gone. Use `sdk.refreshAuth()` (or `sdk.auth.refreshSession()`) to extend a session and `sdk.logout()` (or `sdk.auth.revokeSession()`) to revoke it.
* React: `useAuth` exposes `refreshSession` / `revokeSession` (the old `refreshToken` / `revokeToken` are removed). The `useTokenLifecycle` hook and the provider `tokenLifecycle` prop now persist and refresh the **session** (keypair + expiry); their names and config are unchanged.

For direct REST users:

* `POST /api/v1/auth/challenge` and `POST /api/v1/auth/verify` now require a `session_public_key` (64-char lowercase-hex ed25519 public key). `verify` no longer returns any tokens — only `expires_at` and `user`.
* Every authenticated request must be signed with three headers: `X-Monaco-PublicKey`, `X-Monaco-Timestamp` (Unix milliseconds, within 30 seconds of server time), and `X-Monaco-Signature`. The signature covers `METHOD\npath?query\ntimestamp_ms\nSHA256_hex(body)`.
* `POST /api/v1/auth/refresh` and `POST /api/v1/auth/revoke` now take an empty body and are authenticated with those signing headers.
* Backend services authenticate by sending their `sk_` secret key in the `x-server-key` header on every request — there is no token exchange.

See [TypeScript authentication](https://docs.0xmonaco.com/sdk/typescript/auth.md) and [Authenticating Requests](https://docs.0xmonaco.com/api-reference#authenticating-requests).

## Added: custom API and WebSocket URLs

`SDKConfig` gains optional `apiUrl` and `wsUrl` overrides. When set, the core SDK (`createMonacoSDK` / `new MonacoSDK`) connects to the given URLs instead of the `network` preset's defaults — useful for self-hosted deployments or CI/e2e stacks reachable only by a custom host (e.g. `http://api-gateway:8080`, `ws://ws-api:8080/ws`). `network` still selects the chain. Both must be valid absolute URLs or the constructor throws `InvalidConfigError`.

```typescript theme={null}
const sdk = new MonacoSDK({
  walletClient,
  network: "mainnet",
  seiRpcUrl: "https://evm-rpc.sei-apis.com",
  apiUrl: "http://api-gateway:8080",
  wsUrl: "ws://ws-api:8080/ws",
});
```

## Upgrade

```bash theme={null}
npm install @0xmonaco/core@0.8.8 @0xmonaco/types@0.8.8 @0xmonaco/react@0.8.8
# or bun
bun add @0xmonaco/core@0.8.8 @0xmonaco/types@0.8.8 @0xmonaco/react@0.8.8
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.