diff --git a/README.md b/README.md
index 16d975c..77b65f8 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,28 @@ npm install @webxdc/highscores
## Usage
-Import `@webxdc/highscores` lib (`webxdc.js` also needs to be included) in your `index.html`:
+Quick overview of the API:
+
+```js
+import "@webxdc/highscores";
+
+// always do this first, only use the API after init() finishes
+await window.highscores.init();
+
+// get current player's highscore
+const score = window.highscores.getScore();
+console.log(`your score: ${score}`);
+
+// this will cause an announcement in chat only if it's a new highscore
+window.highscores.setScore(score + 100);
+
+const scoreboard = window.highscores.getHighScores();
+scoreboard.forEach((player) => {
+ console.log(`${player.pos}. ${player.name} - ${player.score}`);
+});
+```
+
+The `webxdc.js` lib also needs to be included in your `index.html`:
```html
@@ -19,15 +40,12 @@ Import `@webxdc/highscores` lib (`webxdc.js` also needs to be included) in your
-
-
- ...
-
+ ...