• Potlock Indexer (Django / Poetry / Celery / NEAR Lake Framework)
  • Stack:
  • Steps to run:
    • Env vars example
  • API Basics
    • Base URL
    • Authorization
    • Error Responses
    • Pagination
  • API Endpoints
    • Account endpoints
      • ✅ Get all accounts: GET /accounts (paginated)
      • ✅ Get account by ID (address): GET /accounts/{ACCOUNT_ID}
      • ✅ Get pots for account: GET /accounts/{ACCOUNT_ID}/active_pots (paginated)
    • List endpoints
      • ✅ Get all lists: GET /lists (paginated)
      • ✅ Get list by ID: GET /lists/{LIST_ID} (paginated)
      • ✅ Get registrations for list: GET /lists/{LIST_ID}/registrations (paginated)
    • Donors endpoints
      • ✅ Get all donors: GET /donors (paginated)
    • Pots endpoints
      • ✅ Get all pots: GET /pots (paginated)
      • ✅ Get applications for pot: GET /pots/{POT_ID}/applications
      • ✅ Get donations for pot: GET /pots/{POT_ID}/donations
      • ✅ Get sponsors for pot: GET /pots/{POT_ID}/sponsors
      • ✅ Get payouts for pot: GET /pots/{POT_ID}/payouts
    • Stats endpoints
      • ✅ Get stats: GET /stats

Potlock Indexer (Django / Poetry / Celery / NEAR Lake Framework)

Stack:

• Django w/ Poetry
• Celery for background indexer task
• NEAR Data Lake Framework for fetching/listening for blocks

Steps to run:

• Set up env vars via ~/.bashrc or ~/.zshrc (see below)
• Install poetry
• Install redis
• Install postgres
• Create postgres database potlock for user postgres
• Activate poetry shell (poetry shell)
• Install dependencies (poetry install)
• Run migrations (python manage.py migrate)
• Update indexer_app.tasks.listen_to_near_events with desired network & start block (if desired)
• Start celery worker with logger (celery -A base worker --loglevel=info)
• Start indexer (python manage.py runindexer)
• Kill indexer (python manage.py killindexer)
  • If for some reason this doesn't kill any active celery tasks, run ps auxww | grep 'celery' | grep -v grep and kill resulting PIDs

Extra commands that might come in useful:

• Purge celery queue (celery -A base purge)

Env vars example

export PL_AWS_ACCESS_KEY_ID=
export PL_AWS_SECRET_ACCESS_KEY=
export PL_CACHALOT_ENABLED=False
export PL_DEBUG=True
export PL_ENVIRONMENT=local
export PL_LOG_LEVEL=debug
export PL_POSTGRES_DB=potlock
export PL_POSTGRES_HOST=127.0.0.1
export PL_POSTGRES_PASS=
export PL_POSTGRES_PORT=5432
export PL_POSTGRES_USER=$USER
export PL_REDIS_HOST=
export PL_REDIS_PORT=6379
export PL_SENTRY_DSN=

API Basics

Base URL

/api/v1/

Authorization

This is a public, read-only API and as such does not currently implement authentication or authorization.

Rate limits of (FILL THIS IN) are enforced to ensure service for all users.

Error Responses

An error response (status code not within range 200-299) will always contain an object body with a message string property containing more information about the error.

Possible Error Codes:

• 400 (Bad Request)
  • Error in client request
• 404 (Not found)
  • Requested resource could not be located
• 500 (Internal Error)
  • Check message string for more information

Pagination

Pagination available using limit and offset query params on endpoints that specify paginated. Default limit is 30.

Endpoints that support pagination will return a success response containing the following:

• count (int) - total number of items available
• next (str | null) - pre-populated endpoint link to the next page of results
• previous (str | null) - pre-populated endpoint link to the previous page of results
• results (any[]) - array of results

API Endpoints

NB: These endpoints are what is required to integrate with BOS app & replace current RPC calls, but more endpoints can easily be added as needed.

Account endpoints

✅ Get all accounts: GET /accounts (paginated)

✅ Get account by ID (address): GET /accounts/{ACCOUNT_ID}

✅ Get pots for account: GET /accounts/{ACCOUNT_ID}/active_pots (paginated)

Can specify status=live query param to retrieve only pots that are currently active (live matching round)

List endpoints

✅ Get all lists: GET /lists (paginated)

✅ Get list by ID: GET /lists/{LIST_ID} (paginated)

✅ Get registrations for list: GET /lists/{LIST_ID}/registrations (paginated)

Can specify status to filter by using status query param if desired, e.g. status=Approved

Donors endpoints

✅ Get all donors: GET /donors (paginated)

Returns all accounts that have sent at least one donation.

Optional query params:

• sort (currently only allowed value is most_donated_usd, which returns results in the order of most to least donated in USD) e.g. ?sort=most_donated_usd

Pots endpoints

NB: POT_ID == on-chain Pot address

✅ Get all pots: GET /pots (paginated)

✅ Get applications for pot: GET /pots/{POT_ID}/applications

✅ Get donations for pot: GET /pots/{POT_ID}/donations

✅ Get sponsors for pot: GET /pots/{POT_ID}/sponsors

✅ Get payouts for pot: GET /pots/{POT_ID}/payouts

Stats endpoints

✅ Get stats: GET /stats

Returns:

• total_donations_usd
• total_payouts_usd
• total_donations_count
• total_donors_count
• total_recipients_count