Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Gratitude? Gratipay! Weekly payments to people and teams you believe in.
Python CSS JavaScript HTML PLpgSQL Shell

Merge pull request #3092 from gratipay/clarify-gratipay-cut

Clarifies that Gratipay doesn't take a cut of payments
latest commit 20faaef699
@whit537 whit537 authored
Failed to load latest commit information.
.tx I renamed the Transifex project
bin migrate code to use exchange routes
docs Change a couple more Gittips to Gratipay
emails Rename Account to Settings
gratipay Merge pull request #3298 from gratipay/fix-cc-expiration
i18n update i18n files
img-src Fixed screenshot link in README fixes #2713
js Fix JS notification callback
scripts vagrant: npm is needed to run jstests
scss generalize the bitcoin code to handle other cryptocoins in the future
sql update schema.sql
tasks fix pyflakes warnings
templates Drop Google Analytics; #761
tests Add tests for scripts
vendor Upgraded setuptools 3.6 -> 14.3.1
www Merge pull request #3092 from gratipay/clarify-gratipay-cut
.babel_extract collect i18n messages from the gratipay lib
.editorconfig Visually optimize a glob in our .editorconfig
.gitattributes Enforce Unix line endings on Windows.
.gitignore Use phantomjs instead of Chrome. Should make Travis happy
.jshintrc ignore jshint warnings about missing optional semicolons
.slugignore Added slugignore file.
.travis.yml Disable pip version check on Travis runs
410.spt i18n of `410.spt` drop "www."
COPYING rename Gittip to Gratipay
Dockerfile Update and improve Dockerfile
Gruntfile.js fix JS tests
Makefile Merge pull request #3282 from gratipay/exchange-routes
Procfile Point gunicorn at our new website instance Rename Account to Settings
Vagrantfile vagrant: add post up message rename Gittip to Gratipay
defaults.env Drop Google Analytics; #761
error.spt prune explicit escaping now that autoescaping is on Upgrade virtualenv 1.11.6 -> 12.0.7 (#3268) This will save me some typing during payday
npm-shrinkwrap.json Use phantomjs instead of Chrome. Should make Travis happy
package.json Use phantomjs instead of Chrome. Should make Travis happy Fix Update path to sql files in a few more places move `branch.sql` into `sql/`
requirements.txt Remove paths in requirements.txt with requirement specs
requirements_tests.txt Remove paths in requirements.txt with requirement specs
runtime.txt Pin Python version using runtime.txt; #3053 fix pyflakes warnings

Welcome to Gratipay

Build Status Coverage Status HuBoard badge Open Bounties

Gratipay is a weekly gift exchange, helping to create a culture of generosity. If you'd like to learn more, check out If you'd like to contribute to Gratipay, check out

Quick Start


Given Python 2.7, Postgres 9.3, and a C/make toolchain:

$ git clone
$ cd
$ sudo -u postgres createuser --superuser $USER
$ createdb gratipay
$ make schema data
$ make run


$ make test

Read more.


Given VirtualBox 4.3 and Vagrant 1.6.x:

$ vagrant up

Read more.


Given some version(?) of Docker:

$ docker build -t gratipay .
$ docker run -p 8537:8537 gratipay

Read more.

Table of Contents


Thanks for hacking on Gratipay! Be sure to review CONTRIBUTING as well if that's what you're planning to do.


Building requires Python 2.7, and a gcc/make toolchain.

All Python library dependencies are bundled in the repo (under vendor/). If you are receiving issues from psycopg2, please ensure that its needs are met.

On Debian or Ubuntu you will need the following packages:

$ sudo apt-get install postgresql-9.3 postgresql-contrib libpq-dev python-dev

On OS X you can download Postgres directly or install through Homebrew:

$ brew install postgresql

To configure local Postgres create default role (if it hasn’t been created already) and database.

$ sudo -u postgres createuser --superuser $USER
$ createdb gratipay

If you are getting an error about unknown argument: '-mno-fused-madd' when running make, then add Wno-error=unused-command-line-argument-hard-error-in-future to your ARCHFLAGS environment variable and run make clean env again (see this Stack Overflow answer for more information):

$ ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future make clean env


All Python dependencies (including virtualenv) are bundled with Gratipay in the vendor/ directory. Gratipay is designed so that you don't manage its virtualenv directly and you don't download its dependencies at build time.

The included Makefile contains several targets. Configuration options are stored in default_local.env file while overrides are in local.env.

To create virtualenv enviroment with all python dependencies installed in a sandbox:

$ make env

If you haven't run Gratipay for a while, you can reinstall the dependencies:

$ make clean env

Add the necessary schemas and insert dummy data into postgres:

$ make schema
$ make data


Once you've installed Python and Postgres and set up a database, you can use make to build and launch Gratipay:

$ make run

If you don't have make, look at the Makefile to see what steps you need to perform to build and launch Gratipay. The Makefile is pretty simple and straightforward.

If Gratipay launches successfully it will look like this:

$ make run
PATH=env/bin:{lots-more-of-your-own-PATH} env/bin/honcho run -e defaults.env,local.env web
2014-07-22 14:53:09 [1258] [INFO] Starting gunicorn 18.0
2014-07-22 14:53:09 [1258] [INFO] Listening at: (1258)
2014-07-22 14:53:09 [1258] [INFO] Using worker: sync
2014-07-22 14:53:09 [1261] [INFO] Booting worker with pid: 1261
pid-1261 thread-140735191843600 (MainThread) Reading configuration from defaults, environment, and command line.
pid-1261 thread-140735191843600 (MainThread)   changes_reload         False                          default
pid-1261 thread-140735191843600 (MainThread)   changes_reload         True                           environment variable ASPEN_CHANGES_RELOAD=yes
pid-1261 thread-140735191843600 (MainThread)   charset_dynamic        UTF-8                          default
pid-1261 thread-140735191843600 (MainThread)   charset_static         None                           default
pid-1261 thread-140735191843600 (MainThread)   configuration_scripts  []                             default
pid-1261 thread-140735191843600 (MainThread)   indices                [u'index.html', u'index.json', u'index', u'index.html.spt', u'index.json.spt', u'index.spt'] default
pid-1261 thread-140735191843600 (MainThread)   list_directories       False                          default
pid-1261 thread-140735191843600 (MainThread)   logging_threshold      0                              default
pid-1261 thread-140735191843600 (MainThread)   media_type_default     text/plain                     default
pid-1261 thread-140735191843600 (MainThread)   media_type_json        application/json               default
pid-1261 thread-140735191843600 (MainThread)   project_root           None                           default
pid-1261 thread-140735191843600 (MainThread)   project_root           .                              environment variable ASPEN_PROJECT_ROOT=.
pid-1261 thread-140735191843600 (MainThread)   renderer_default       stdlib_percent                 default
pid-1261 thread-140735191843600 (MainThread)   show_tracebacks        False                          default
pid-1261 thread-140735191843600 (MainThread)   show_tracebacks        True                           environment variable ASPEN_SHOW_TRACEBACKS=yes
pid-1261 thread-140735191843600 (MainThread)   www_root               None                           default
pid-1261 thread-140735191843600 (MainThread)   www_root               www/                           environment variable ASPEN_WWW_ROOT=www/
pid-1261 thread-140735191843600 (MainThread) project_root is relative to CWD: '.'.
pid-1261 thread-140735191843600 (MainThread) project_root set to /Users/whit537/personal/gratipay/
pid-1261 thread-140735191843600 (MainThread) Found plugin for renderer 'jinja2'
pid-1261 thread-140735191843600 (MainThread) Won't log to Sentry (SENTRY_DSN is empty).
pid-1261 thread-140735191843600 (MainThread) Renderers (*ed are unavailable, CAPS is default):
pid-1261 thread-140735191843600 (MainThread)   stdlib_percent
pid-1261 thread-140735191843600 (MainThread)   json_dump
pid-1261 thread-140735191843600 (MainThread)   stdlib_format
pid-1261 thread-140735191843600 (MainThread)   JINJA2
pid-1261 thread-140735191843600 (MainThread)   stdlib_template

You should then find this in your browser at http://localhost:8537/:


Congratulations! Sign in using Twitter or GitHub and you're off and running. At some point, try running the test suite.


Gratipay's default configuration lives in defaults.env. If you'd like to override some settings, create a file named local.env to store them.

The following explains some of the content of that file:

The BALANCED_API_SECRET is a test marketplace. To generate a new secret for your own testing run this command:

curl -X POST | grep secret

Grab that secret and also create a new marketplace to test against:

curl -X POST -u <your_secret>:

The site works without this, except for the credit card page. Visit the Balanced Documentation if you want to know more about creating marketplaces.

The GITHUB_* keys are for a gratipay-dev application in the Gratipay organization on Github. It points back to localhost:8537, which is where Gratipay will be running if you start it locally with make run. Similarly with the TWITTER_* keys, but there they required us to spell it

If you wish to use a different username or database name for the database, you should override the DATABASE_URL in local.env using the following format:

DATABASE_URL=postgres://<username>@localhost/<database name>

The MANDRILL_KEY value in defaults.env is for a test mail server, which won't actually send email to you. If you need to receive email during development then sign up for an account of your own at Mandrill and override MANDRILL_KEY in your local.env.


If you have Vagrant installed, you can run Gratipay by running vagrant up from the project directory. Please note that if you ever switch between running Gratipay on your own machine to Vagrant or vice versa, you will need to run make clean.

If you're using Vagrant for the first time you'll need Vagrant and VirtualBox installed. If you're on Linux you'll need to install nfs-kernel-server.

The Vagrantfile will download a custom made image from the Internet. If you have a slow internet connection, you can download a local copy of this file, by running:


Once downloaded into the top of the project tree, our Vagrantfile will use this local file automatically when you run vagrant up. Vagrant is setup to use key based SSH authentication, if you're prompted for a password when logging in please use vagrant.

Mac users: If you're prompted for a password during initial installation, it's sudo and you should enter your Mac OS password.

Ubuntu users: If you experience problems, please see this issue. As mentioned, you will also need to be wary of projects that are nested in encrypted directories.


You can also install/run Gratipay with Docker.

Build it with the included Dockerfile:

$ git clone
$ cd
$ docker build -t gratipay .

Once you've built the image, you can launch a container:

$ docker run -d -p 8537:8537 gratipay

Check it out at localhost:8537!

To edit files and have those changes reflect in the running container, mount your local folder when you execute the run command:

$ docker run -d -v $PWD:/srv/ -p 8537:8537 gratipay

You can get the running container's ID with docker ps. With that, you can

  • view the logs:
$ docker logs [container_id]
  • run commands within the project root:
$ docker exec [container_id] make schema
$ docker exec [container_id] make data

Once you're done, kill the running container:

$ docker kill [container_id]


If you get stuck somewhere along the way, you can find help in the #gratipay channel on Freenode or in the issue tracker here on GitHub.

Thanks for installing Gratipay! :smiley:

Modifying CSS

We use SCSS, with files stored in scss/. All of the individual files are combined in scss/gratipay.scss which itself is compiled by libsass in www/assets/%version/gratipay.css.spt on each request.

Modifying the Database

We write SQL, specifically the PostgreSQL variant. We keep our database schema in schema.sql, and we write schema changes for each PR branch in a sql/branch.sql file, which then gets run against production and merged into sql/schema.sql during deployment.

Testing Build Status

Please write unit tests for all new code and all code you change. Gratipay's test suite uses the py.test test runner, which will be installed into the virtualenv you get by running make env. As a rule of thumb, each test case should perform one assertion.

The easiest way to run the test suite is:

$ make test

However, the test suite deletes data in all tables in the public schema of the database configured in your testing environment.

To invoke py.test directly you should use the honcho utility that comes with the install. First make tests/env, activate the virtualenv and then:

[gratipay] $ cd tests/
[gratipay] $ honcho run -e defaults.env,local.env py.test

Local Database Setup

For the best development experience, you need a local installation of Postgres. The best version of Postgres to use is 9.3.2, because that's what we're using in production at Heroku. You need at least 9.2, because we depend on being able to specify a URI to psql, and that was added in 9.2.

  • Mac: use Homerew: brew install postgres
  • Ubuntu: use Apt: apt-get install postgresql postgresql-contrib libpq-dev

To setup the instance for gratipay's needs run:

$ sudo -u postgres createuser --superuser $USER
$ createdb gratipay
$ createdb gratipay-test

You can speed up the test suite when using a regular HDD by running:

$ psql -q gratipay-test -c 'alter database "gratipay-test" set synchronous_commit to off'


Once Postgres is set up, run:

$ make schema

Which populates the database named by DATABASE_URL with the schema from sql/schema.sql.

Example data

The gratipay database created in the last step is empty. To populate it with some fake data, so that more of the site is functional, run this command:

$ make data


The Gratipay API is comprised of these six endpoints:

/about/charts.json (source)—public—Returns an array of objects, one per week, showing aggregate numbers over time. The stats page uses this.

/about/paydays.json (source)—public—Returns an array of objects, one per week, showing aggregate numbers over time. The old charts page used to use this.

/about/stats.json (source)—public—Returns an object giving a point-in-time snapshot of Gratipay. The stats page displays the same info.

/%username/charts.json (example, source)—public—Returns an array of objects, one per week, showing aggregate numbers over time for the given user.

/%username/public.json (example, source)—public—Returns an object with these keys:

  • "receiving"—an estimate of the amount the given participant will receive this week

  • "my_tip"—logged-in user's tip to the Gratipay participant in question; possible values are:

    • undefined (key not present)—there is no logged-in user
    • "self"—logged-in user is the participant in question
    • null—user has never tipped this participant
    • "0.00"—user used to tip this participant
    • "3.00"—user tips this participant the given amount

  • "goal"—funding goal of the given participant; possible values are:

    • undefined (key not present)—participant is a patron (or has 0 as the goal)
    • null—participant is grateful for gifts, but doesn't have a specific funding goal
    • "100.00"—participant's goal is to receive the given amount per week

  • "elsewhere"—participant's connected accounts elsewhere; returns an object with these keys:

    • "bitbucket"—participant's Bitbucket account; possible values are:
      • undefined (key not present)—no Bitbucket account connected
    • "github"—participant's GitHub account; possible values are:
      • undefined (key not present)—no GitHub account connected
    • "twitter"—participant's Twitter account; possible values are:
      • undefined (key not present)—no Twitter account connected
    • "openstreetmap"—participant's OpenStreetMap account; possible values are:
      • undefined (key not present)—no OpenStreetMap account connected

/%username/tips.json (source)—private—Responds to GET with an array of objects representing your current tips. POST the same structure back in order to update tips in bulk (be sure to set Content-Type to application/json instead of application/x-www-form-urlencoded). You can POST a partial array to update a subset of your tips. The response to a POST will be only the subset you updated. If the amount is "error" then there will also be an error attribute with a one-word error code. If you include an also_prune key in the querystring (not the body!) with a value of yes, true, or 1, then any tips not in the array you POST will be zeroed out.

NOTE: The amounts must be encoded as a string (rather than a number). Additionally, currently, the only supported platform is 'gratipay' ('gittip' still works for backwards-compatibility).

This endpoint requires authentication. Look for your user ID and API key on your account page, and pass them using basic auth. E.g.:

curl \
    -u $userid:$api_key \
    -X POST \
    -d'[{"username":"bazbuz", "platform":"gratipay", "amount": "1.00"}]' \
    -H"Content-Type: application/json"

API Implementations

Below are some projects that use the Gratipay APIs, that can serve as inspiration for your project!

Renamed to Gratipay

Still Using Gittip

These probably still work, but are using our old name:


Account Elsewhere - An entity's registration on a platform other than Gratipay (e.g., Twitter).

Entity - An entity.

Participant - An entity registered with Gratipay.

User - A person using the Gratipay website. Can be authenticated or anonymous. If authenticated, the user is guaranteed to also be a participant.


Gratipay is dedicated to public domain. See the text of CC0 1.0 Universal dedication in COPYING here.

Something went wrong with that request. Please try again.