diff --git a/readme.md b/readme.md
index a04039f..8c2cf27 100644
--- a/readme.md
+++ b/readme.md
@@ -33,13 +33,47 @@ API
     int ed25519_create_seed(unsigned char *seed);
 
 Creates a 32 byte random seed in `seed` for key generation. `seed` must be a
-writable 32 byte buffer.
+writable 32 byte buffer. Returns 0 on success, and nonzero on failure.
 
     int ed25519_create_keypair(unsigned char *verify_key, unsigned char *sign_key, const unsigned char *seed);
 
 Creates a new key pair from the given seed. `verify_key` must be a writable 32
 byte buffer, `sign_key` must be a writable 64 byte buffer and `seed` must be a
-32 byte buffer.
+32 byte buffer.  Returns 0 on success, and nonzero on failure.
 
-    int ed25519_sign(unsigned char *signature, const unsigned char *message, size_t message_len, const unsigned char *sign_key);
-    int ed25519_verify(const unsigned char *signature, const unsigned char *message, size_t message_len, const unsigned char *verify_key);
\ No newline at end of file
+    int ed25519_sign(unsigned char *signature,
+                     const unsigned char *message, size_t message_len,
+                     const unsigned char *sign_key);
+
+Creates a signature of the given message with `sign_key`. `signature` must be
+a writable 64 byte buffer. `message` must have at least `message_len` bytes to
+be read. `sign_key` must be a 64 byte signing key generated by
+`ed25519_create_keypair`. Returns 0 on success, and nonzero on failure.
+
+    int ed25519_verify(const unsigned char *signature,
+                       const unsigned char *message, size_t message_len,
+                       const unsigned char *verify_key);
+
+Verifies the signature on the given message using verify_key. `signature` must be
+a readable 64 byte buffer. `message` must have at least `message_len` bytes to
+be read. `sign_key` must be a 32 byte verifying key generated by
+`ed25519_create_keypair`. Returns 0 if the signature matches, 1 otherwise.
+
+Example
+-------
+    unsigned char seed[32], sign_key[64], verify_key[32], signature[64];
+    const unsigned char message[] = "TEST MESSAGE";
+
+    /* create a random seed, and a keypair out of that seed */
+    ed25519_create_seed(seed);
+    ed25519_create_keypair(verify_key, sign_key, seed);
+
+    /* create signature on the message with the sign key */
+    ed25519_sign(signature, message, strlen(message), sign_key);
+
+    /* verify the signature */
+    if (ed25519_verify(signature, message, strlen(message), verify_key)) {
+        printf("invalid signature\n");
+    } else {
+        printf("valid signature\n");
+    }
\ No newline at end of file