Skip to main content

Local Development

Run the urblock API locally to develop and test integrations against a real instance.

Prerequisites​

  • Node.js >= 20 and pnpm >= 9
  • Docker (for Postgres + Redis)
  • A testnet RPC URL (e.g. Sepolia) and a funded dev key for on-chain calls

Setup​

git clone https://github.com/urblock/urblock
cd urblock
pnpm install

Copy the example environment and fill in the required values:

cp apps/api/.env.example apps/api/.env

Key variables:

VariablePurpose
DATABASE_URLPostgres connection (use the app_user role, not a superuser)
REDIS_URLRedis connection (require a password)
MASTER_SEED_PHRASEBIP-39 mnemonic for the platform signer
WALLET_ENCRYPTION_KEY32-byte hex key for wallet encryption
JWT_SECRET / JWT_REFRESH_SECRETAuth signing keys
CORS_ORIGINSComma-separated allowed browser origins (or * for all)
PLATFORM_ADMIN_SECRETSecret for /v1/admin/* endpoints

Run​

# start Postgres + Redis
docker compose up -d postgres redis

# run the API (http://localhost:3000)
pnpm --filter @urblock/api dev
  • Health check: curl http://localhost:3000/health
  • OpenAPI JSON: http://localhost:3000/docs-json
  • Swagger UI: http://localhost:3000/docs

Get a test API key​

Register a tenant, then create a secret key:

curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"you@example.com\",\"password\":\"Password123\",\"company_name\":\"Acme\",\"full_name\":\"You\"}"

Use the returned JWT to create an API key (sk_test_...), then call the API:

curl http://localhost:3000/v1/tokens -H "Authorization: Bearer sk_test_..."

Testnet funding​

For on-chain calls on Sepolia, fund your account from a faucet (e.g. faucet.urblock.io) before deploying tokens.

Tests​

pnpm --filter @urblock/api test     # backend unit + e2e
pnpm --filter @urblock/sdk test     # SDK