diff --git a/README.rst b/README.rst index db21d83..a387069 100644 --- a/README.rst +++ b/README.rst @@ -132,7 +132,7 @@ Bug reports, suggestions, and patches are always welcome! Submit issues `here `__. ``schwab-py`` is released under the -`MIT license `__. +`MIT license `__. **Disclaimer:** *schwab-py is an unofficial API wrapper. It is in no way endorsed by or affiliated with Charles Schwab or any associated organization. diff --git a/docs/_static/setting-up-api-product.png b/docs/_static/setting-up-api-product.png new file mode 100644 index 0000000..13aff68 Binary files /dev/null and b/docs/_static/setting-up-api-product.png differ diff --git a/docs/_static/setting-up-approved-pending.png b/docs/_static/setting-up-approved-pending.png new file mode 100644 index 0000000..8da5661 Binary files /dev/null and b/docs/_static/setting-up-approved-pending.png differ diff --git a/docs/_static/setting-up-callback-url-error.png b/docs/_static/setting-up-callback-url-error.png new file mode 100644 index 0000000..b93674c Binary files /dev/null and b/docs/_static/setting-up-callback-url-error.png differ diff --git a/docs/_static/setting-up-callback-url.png b/docs/_static/setting-up-callback-url.png new file mode 100644 index 0000000..f866eea Binary files /dev/null and b/docs/_static/setting-up-callback-url.png differ diff --git a/docs/_static/setting-up-create-app.png b/docs/_static/setting-up-create-app.png new file mode 100644 index 0000000..215f1e2 Binary files /dev/null and b/docs/_static/setting-up-create-app.png differ diff --git a/docs/_static/setting-up-name-and-description.png b/docs/_static/setting-up-name-and-description.png new file mode 100644 index 0000000..9c1cef5 Binary files /dev/null and b/docs/_static/setting-up-name-and-description.png differ diff --git a/docs/_static/setting-up-order-limit.png b/docs/_static/setting-up-order-limit.png new file mode 100644 index 0000000..1a7fcd8 Binary files /dev/null and b/docs/_static/setting-up-order-limit.png differ diff --git a/docs/_static/setting-up-ready-for-use.png b/docs/_static/setting-up-ready-for-use.png new file mode 100644 index 0000000..1721654 Binary files /dev/null and b/docs/_static/setting-up-ready-for-use.png differ diff --git a/docs/_static/setting-up-secrets.png b/docs/_static/setting-up-secrets.png new file mode 100644 index 0000000..1a384cf Binary files /dev/null and b/docs/_static/setting-up-secrets.png differ diff --git a/docs/auth.rst b/docs/auth.rst index 97a0361..96ca65e 100644 --- a/docs/auth.rst +++ b/docs/auth.rst @@ -74,12 +74,12 @@ implementations of this flow, and ``schwab-py``'s authentication module makes using them easy. +.. _login_flow: + -------------------------------------- Fetching a Token and Creating a Client -------------------------------------- -.. _login_flow: - This function will guide you through the process of logging in and creating a token. @@ -329,8 +329,9 @@ What If I Can't Use a Browser? ++++++++++++++++++++++++++++++ Launching a browser can be inconvenient in some situations, most notably in -containerized applications running on a cloud provider. ``tda-api`` supports two -alternatives to creating tokens by opening a web browser. +containerized applications running on a cloud provider, or when running in a +notebook. ``schwab-py`` supports two alternatives to creating tokens by opening +a web browser. Firstly, the :ref:`manual login flow` flow allows you to go through the login flow on a different machine than the one on which diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 1b314a5..407e845 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -20,24 +20,54 @@ you'll have accomplished the three prerequisites for using ``schwab-py``: #. Choose and save the callback URL (important for authenticating). #. Receive an app key and a secret. +**Create a Developer Account** + You can create a developer account `here `__. The instructions from here on out assume you're logged in, so make sure you log into the developer site after you've created your account. +**Create an Application** + +.. figure:: _static/setting-up-create-app.png + Next, you'll want to `create an application `__ and populate the -required fields. The first thing you'll select is the API Product. We in the -community aren't currently clear on the difference between the options -("Accounts and Trading" and "Market Data"). It seems that selecting "Accounts -and Trading" grants access to all APIs supported by ``schwab-py``, so unless you +required fields. + +**API Product** + +.. figure:: _static/setting-up-api-product.png + +The first thing you'll select is the API Product. We in the community aren't +currently clear on the difference between the options ("Accounts and Trading +Production" and "Market Data"). It seems that selecting "Accounts and Trading +Production" grants access to all APIs supported by ``schwab-py``, so unless you have a reason to do differently, we recommend selecting that option. +**Order Limit** + +.. figure:: _static/setting-up-order-limit.png + +The order limit is the number of order-related requests your app will be +permitted to place each minute. If you make, cancel, or replace more than this +many orders each minute, you'll be throttled and your orders will be rejected. +Most users have no reason to restrict this, so we recommend setting this to 120. + +**App Name and Description** + +.. figure:: _static/setting-up-name-and-description.png + Next are the app name and description. ``schwab-py`` does not use these values, but the folks at at Schwab might. We recommend being descriptive here, if only so that users and app approvers know what your app will do. -Next is the callback URL. In a nutshell, the `OAuth login flow +**App Name and Description** + +.. figure:: _static/setting-up-callback-url.png + +Finally, we have the callback URL. This one is important. In a nutshell, the +`OAuth login flow `__ that Schwab uses works by opening a login page, securely collecting credentials on their domain, and then @@ -53,6 +83,11 @@ number is not require to use ``schwab-py``, but it is required to use use a non-local callback URL, but this documentation assumes they are advanced enough not to need our help creating such a setup. +*Update July 21, 2024:* We are receiving intermittent reports that Schwab is +refusing to create apps with callback URLs containing ``127.0.0.1``. If you +encounter this, please let our Discord community know in our `help channel +`__. + In any case, note that whatever callback URL you choose, you must pass it to ``schwab-py`` *exactly* in the same way as you specified it while creating your app. Any deviation (including adding or removing a trailing slash!) can cause @@ -60,16 +95,28 @@ difficult-to-debug issues. Be careful not to mis-copy this value. .. _approved_pending: +**Waiting for Approval** + +.. figure:: _static/setting-up-approved-pending.png + +.. figure:: _static/setting-up-ready-for-use.png + After your app is created, you will likely see it in an ``Approved - Pending`` state when you view it in your dashboard. Don't be fooled by the word ``Approved``: your app is not yet ready for use. You must wait for Schwab to *actually* approve it, at which point its status will be ``Ready For Use.`` This can take up to a few days. Only then can you proceed to using ``schwab-py``. -Once your app is created and approved, you will receive your app key and secret. -Neither of these are meant to be shared by anyone, so keep them safe. You will -also be required to pass these into ``schwab-py``. This library does not share -these values with anyone except official Schwab endpoints. +**Client Secrets** + +.. figure:: _static/setting-up-secrets.png + +Once your app is created and approved, you will be able to access your app key +and app secret by clicking through to your approved application in the +dashobard. Neither of these are meant to be shared by anyone, so keep them safe +(the ones displayed here are fake). You will also be required to pass these into +``schwab-py``. This library does not share these values with anyone except +official Schwab endpoints, not even its authors. Don't share them with anyone. ++++++++++++++++++++++++ Installing ``schwab-py``