diff --git a/.idea/gradle.xml b/.idea/gradle.xml
index f1c0953..a56718e 100644
--- a/.idea/gradle.xml
+++ b/.idea/gradle.xml
@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
+  <component name="GradleMigrationSettings" migrationVersion="1" />
   <component name="GradleSettings">
     <option name="linkedExternalProjectsSettings">
       <GradleProjectSettings>
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8b3abdb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,104 @@
+# SMTShell-API
+
+SMTShell-API is an Android library that provides methods for executing shell commands and loading shared objects **as the system user (UID 1000)** on Samsung devices that are running **SMTShell**.
+
+## Including this in your project
+
+**project build.gradle**
+```gradle
+allprojects {
+    repositories {
+        // other repos here
+        maven { url "https://jitpack.io" }  // <--- add this
+    }
+}
+```
+
+**app/module build.gradle**
+```gradle
+dependencies {
+    implementation 'com.github.BLuFeNiX:SMTShell-API:1.0'
+}
+```
+
+## Get permissions
+
+Declare one or both of these, and arrange for your user to grant them as per usual:
+
+```
+<uses-permission android:name="smtshell.permission.SYSTEM_COMMAND" />
+<uses-permission android:name="smtshell.permission.LOAD_LIBRARY" />
+```
+
+## API Methods
+
+### executeCommand
+
+`executeCommand(Context context, String cmd)`
+`executeCommand(Context context, String cmd, CommandCallback cb)`
+
+```java
+SMTShellAPI.executeCommand(context, "ls -la /data/data/android/", new SMTShellAPI.CommandCallback() {
+    @Override
+    public void onComplete(String stdout, String stderr, int exitCode) {
+        Log.d(TAG, "stdout: " + stdout);
+        Log.d(TAG, "stderr: " + stderr);
+        Log.d(TAG, "exit code: " + exitCode);
+    }
+});
+```
+
+### loadLibrary
+
+`loadLibrary(Context context, String path)`
+`loadLibrary(Context context, String path, LoadLibraryCallback cb)`
+
+Load a shared object as the system (UID 1000).
+
+```java
+SMTShellAPI.loadLibrary(this, getApplicationInfo().nativeLibraryDir + "/" + "libsmtshell.so", new SMTShellAPI.LoadLibraryCallback() {
+    @Override
+    public void onComplete(boolean success) {
+        if (success) {
+            // library loaded!
+        } else {
+            // something went wrong!
+        }
+    }
+});
+```
+> Note: Callback will not fire if your shared object blocks the incoming thread (i.e., with an onload constructor).
+
+### ping
+
+`ping(Context context)`
+
+Pings the API. You can capture the result with a dynamic broadcast receiver:
+
+```java
+BroadcastReceiver mApiReadyReceiver = new BroadcastReceiver() {
+    @Override
+    public void onReceive(Context context, Intent intent) {
+        // API is ready!
+    }
+};
+
+@Override
+protected void onResume() {
+    super.onResume();
+    registerReceiver(mApiReadyReceiver, new IntentFilter(SMTShellAPI.ACTION_API_READY));
+    SMTShellAPI.ping(this);
+}
+
+@Override
+protected void onPause() {
+    super.onPause();
+    unregisterReceiver(mApiReadyReceiver);
+}
+```
+
+You can also monitor the API going down (because the user killed it) via a recevier:
+
+```java
+registerReceiver(mApiDeathReceiver, new IntentFilter(SMTShellAPI.ACTION_API_DEATH_NOTICE));
+```
diff --git a/api/src/main/java/net/blufenix/smtshell/api/SMTShellAPI.java b/api/src/main/java/net/blufenix/smtshell/api/SMTShellAPI.java
new file mode 100644
index 0000000..4b05877
--- /dev/null
+++ b/api/src/main/java/net/blufenix/smtshell/api/SMTShellAPI.java
@@ -0,0 +1,140 @@
+package net.blufenix.smtshell.api;
+
+import android.app.PendingIntent;
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+import android.content.IntentFilter;
+
+import java.util.concurrent.atomic.AtomicInteger;
+
+public class SMTShellAPI {
+
+    // requests
+    public static final String ACTION_SHELL_COMMAND = "smtshell.intent.action.SHELL_COMMAND";
+    public static final String EXTRA_COMMAND = "smtshell.intent.extra.COMMAND";
+    public static final String EXTRA_REQUEST_ID = "smtshell.intent.extra.REQUEST_ID";
+    public static final String EXTRA_CALLBACK_PKG = "smtshell.intent.extra.CALLBACK_PKG"; // IntentSender
+    public static final String PKG_NAME_SMT = "com.samsung.SMT"; // send requests to this pkg
+
+    public static final String ACTION_LOAD_LIBRARY = "smtshell.intent.action.ACTION_LOAD_LIBRARY";
+    public static final String EXTRA_LIBRARY_PATH = "smtshell.intent.extra.EXTRA_LIBRARY_PATH";
+
+    public static final String ACTION_API_PING = "smtshell.intent.action.API_PING";
+
+    // results
+    public static final String ACTION_SHELL_RESULT = "smtshell.intent.action.SHELL_RESULT";
+    public static final String EXTRA_STDOUT = "smtshell.intent.extra.STDOUT";
+    public static final String EXTRA_STDERR = "smtshell.intent.extra.STDERR";
+    public static final String EXTRA_EXIT_CODE = "smtshell.intent.extra.EXIT_CODE";
+
+    public static final String ACTION_LOAD_LIBRARY_RESULT = "smtshell.intent.action.LOAD_LIBRARY_RESULT";
+    public static final String EXTRA_LOAD_SUCCESS = "smtshell.intent.extra.LOAD_SUCCESS";
+
+    public static final String ACTION_API_READY = "smtshell.intent.action.API_READY";
+    public static final String ACTION_API_DEATH_NOTICE = "smtshell.intent.action.API_DEATH_NOTICE";
+
+    // permissions
+    public static final String PERMISSION_SYSTEM_COMMAND = "smtshell.permission.SYSTEM_COMMAND";
+    public static final String PERMISSION_LOAD_LIBRARY = "smtshell.permission.LOAD_LIBRARY";
+    public static final String PERMISSION_RECEIVER_GUARD = "android.permission.REBOOT";
+
+    // start at a number a user is unlikely to use for themselves,
+    //  in case they manually call the API without the wrapper
+    private static final AtomicInteger REQUEST_ID = new AtomicInteger(1000000);
+    static int nextId() {
+        return REQUEST_ID.getAndIncrement();
+    }
+
+    public static void executeCommand(Context context, String cmd) {
+        executeCommand(context, cmd, null);
+    }
+
+    public static void executeCommand(Context context, String cmd, CommandCallback cb) {
+        // setup intent
+        int requestId = nextId();
+        Intent intent = createIntent(ACTION_SHELL_COMMAND, requestId);
+        intent.putExtra(EXTRA_COMMAND, cmd);
+
+        if (cb != null) {
+            // specify that the request has a sender
+            setSender(context, intent);
+            // setup receiver
+            context.registerReceiver(new BroadcastReceiver() {
+                @Override
+                public void onReceive(Context context, Intent intent) {
+                    if (requestId == intent.getIntExtra(EXTRA_REQUEST_ID, -1)) {
+                        context.unregisterReceiver(this);
+                        cb.onComplete(
+                                intent.getStringExtra(EXTRA_STDOUT),
+                                intent.getStringExtra(EXTRA_STDERR),
+                                intent.getIntExtra(EXTRA_EXIT_CODE, -1)
+                        );
+                    }
+                }
+            }, new IntentFilter(ACTION_SHELL_RESULT), PERMISSION_RECEIVER_GUARD, null);
+        }
+
+        // send command
+        context.sendBroadcast(intent);
+    }
+
+    public static void loadLibrary(Context context, String path) {
+        loadLibrary(context, path, null);
+    }
+
+    public static void loadLibrary(Context context, String path, LoadLibraryCallback cb) {
+        // setup intent
+        int requestId = nextId();
+        Intent intent = createIntent(ACTION_LOAD_LIBRARY, requestId);
+        intent.putExtra(EXTRA_LIBRARY_PATH, path);
+
+        if (cb != null) {
+            // specify that the request has a sender
+            setSender(context, intent);
+            // setup receiver
+            context.registerReceiver(new BroadcastReceiver() {
+                @Override
+                public void onReceive(Context context, Intent intent) {
+                    if (requestId == intent.getIntExtra(EXTRA_REQUEST_ID, -1)) {
+                        context.unregisterReceiver(this);
+                        cb.onComplete(intent.getBooleanExtra(EXTRA_LOAD_SUCCESS, false));
+                    }
+                }
+            }, new IntentFilter(ACTION_LOAD_LIBRARY_RESULT), PERMISSION_RECEIVER_GUARD, null);
+        }
+
+        // send the command
+        context.sendBroadcast(intent);
+    }
+
+    public static void ping(Context context) {
+        Intent intent = createIntent(ACTION_API_PING, -1);
+        setSender(context, intent);
+        context.sendBroadcast(intent);
+    }
+
+    static Intent createIntent(String action, int requestId) {
+        Intent intent = new Intent(action);
+        intent.setPackage(PKG_NAME_SMT);
+        intent.putExtra(EXTRA_REQUEST_ID, requestId);
+        return intent;
+    }
+
+    // used to prove where the intent came from, so other packages can't request things on our behalf
+    static void setSender(Context context, Intent intent) {
+        int flags = PendingIntent.FLAG_IMMUTABLE;
+        PendingIntent self = PendingIntent.getBroadcast(context, 0, new Intent(), flags);
+        intent.putExtra(EXTRA_CALLBACK_PKG, self.getIntentSender());
+    }
+
+    public interface CommandCallback {
+        void onComplete(String stdout, String stderr, int exitCode);
+    }
+
+    public interface LoadLibraryCallback {
+        void onComplete(boolean success);
+    }
+
+}
+