Getting Started

Welcome to Locus! This guide will walk you through everything you need to start building AI agents with payment capabilities.

Overview

To get started with Locus, you'll need to:

  1. Sign up for a Locus account

  2. Create a wallet

  3. Fund your wallet

  4. Create a policy group

  5. Get your API credentials

  6. Initialize your project with our CLI tool

The entire setup process takes about 10-15 minutes.

What You'll Need

Before you begin, make sure you have:

  • A modern web browser

  • Node.js 14 or higher installed

  • npm or yarn package manager

  • An Anthropic API key (for AI features)

Step 1: Sign Up

Create your Locus account to get started with the platform.

Sign Up Process

  1. Visit app.paywithlocus.com

  2. Click on "Sign Up" or "Create Account"

Step 2: Create a Wallet

Set up your Locus wallet to manage payments and funds.

Creating Your Wallet

  1. Navigate to the Wallets section in the site or go to https://app.paywithlocus.com/dashboard/wallets

  2. Click "Create New Wallet" or "Add Wallet"

  1. Configure your wallet:

  • Chain (Base Mainnet or Sepolia Testnet)

  • Wallet name (e.g., "Production Wallet", "Development Wallet")

  • Download a json of your private key (NOTE: this will never be shown again)

  1. Confirm and create

Review your settings and click "Deploy Wallet" to finalize.

Wallet Created

Your wallet is now ready to receive funds. You'll see your new wallet listed in your dashboard with:

  • Wallet Address

  • Current balance (currently $0.00)

  • Status of Session Key

Step 3: Fund Your Wallet

Add funds to your Locus wallet to start testing payments.

Mainnet: Funding Your Wallet

  1. Navigate to your wallet in the dashboard

  2. Click "Add"

  3. Follow the instructions in Coinbase OnRamp

If you already have USDC on Base you can send to the wallet address listed

Troubleshooting

Funds not showing up?

  • Wait a few minutes and refresh

  • Check your email for payment confirmation

  • Verify the transaction was successful

  • Contact support if funds don't appear within 30 minutes

Want to add more funds later?

  • You can add funds at any time using the same process

  • Your balance updates in real-time

Step 4: Create a Policy Group

Configure payment policies to control how your agent is able to spend money.

What is a Policy Group?

A policy group defines the rules and permissions for your payments:

  • Monthly Budgets

  • Allowed payment methods

  • Approved contacts

Creating a Policy Group

  1. Navigate to the Agents page or go to https://app.paywithlocus.com/dashboard/agents

  2. Click "Create Policy Group" or "New Policy"

  1. Configure your policy settings:

    Basic Information:

    • Policy group name (e.g., "Production Policy", "Dev Policy")

    Associated Wallet:

    • Select the wallet you created from the last step

    Agent Permissions:

    • Allow agents to send funds to email addresses

    • Allow agents to send funds to wallet addresses

    • Allow agents to send funds to contacts

    • Whitelist particular contacts (Create contacts in the contacts tab or at https://app.paywithlocus.com/dashboard/contacts)

  2. Review and create

Double-check your settings and click "Create Policy Group"

Policy Group Created

Your policy group is now active and ready to use with your applications.

Step 5: Get Your Credentials

Retrieve your API credentials to connect your application to Locus.

Types of Credentials

Locus offers two types of authentication:

OAuth Client Credentials (Recommended for Production)

  • Client ID and Client Secret

  • More secure

  • Best for production applications

  • Used with LangChain framework

API Key (Simple Authentication)

  • Single API key

  • Easier to set up

  • Good for prototypes and development

  • Used with Claude SDK

Getting Your Credentials

  1. Navigate to the Agents page or go to https://app.paywithlocus.com/dashboard/agents

  2. Create a new agent

  1. Enter name and memo (optional)

  2. Optionally generate an API key for the agent (NOTE: API key is less secure than OAuth. OAuth is less widely supported however so we give you the option for either)

  3. Click "Create Agent"

  4. Copy your generated Client ID, Client Secret, and API key to a secure place like a .env file

Storing Your Credentials Securely

Never commit credentials to version control!

Create a .env file in your project:

Add .env to your .gitignore file to keep credentials safe.

Troubleshooting

Lost your Client Secret or API Key?

  • You'll need to create a new one

  • Delete the old credentials and generate new ones

  • Update your application with the new credentials

Credentials not working?

  • Double-check you copied them correctly (no extra spaces)

  • Verify the credentials are associated with the correct wallet and policy group

Step 6: Initialize Your Project

Use our CLI tool to create a ready-to-run Locus application.

Prerequisites

Before running the CLI, make sure you have:

  • Node.js 14 or higher installed

  • Your Locus credentials (from Step 5)

  • An Anthropic API key (Get one here) or OpenAI key (Get one here) with credits

Create Your Locus App

1. Run the Create Command

Open your terminal and run:

Or specify a project name:

2. Follow the Interactive Prompts

The CLI will guide you through setup:

Project Name

If you didn't specify a name in the command, you'll be prompted:

Choose Your Framework

You'll be asked to select a framework:

LangChain (OAuth)

  • More secure with Client ID/Secret

  • Full MCP integration

  • LangChain ReAct agent

  • Recommended for production

Claude SDK (API Key)

  • Simpler setup with single API key

  • Claude SDK

  • Streaming support

  • Great for prototypes

Enter Your Credentials

Depending on your framework choice:

For LangChain:

For Claude SDK:

Your credentials are entered securely (hidden input) and never logged.

3. Installation Process

The CLI will automatically:

  1. Create your project directory

  2. Copy template files

  3. Configure environment variables

  4. Install dependencies

  5. Initialize git repository

  6. Set up proper file permissions

Run Your Application

Once setup is complete:

Your app is ready to run immediately!

Project Structure

Your new project includes:

What's Included

Your generated app comes with:

  • 🔐 Authentication configured (OAuth or API Key)

  • 🤖 AI agent setup with Claude

  • 🎯 Sample code demonstrating Locus features

  • 📦 All dependencies installed

  • 📝 Comprehensive README with examples

Next Steps

Now that your project is set up, you can:

  1. Explore the sample code - See how Locus and Claude work together

  2. Read the project README - Learn about available features

  3. Start building - Modify the code for your project

  4. Test payments - Use your funded wallet to test transactions

Customizing Your App

The generated app is a starting point. You can:

  • Add new AI agent capabilities

  • Integrate additional APIs

  • Build a web interface

  • Add database persistence

  • Deploy to production

Check your project's README for specific customization guides based on your chosen framework.

Troubleshooting

Command not found?

Installation fails?

  • Check your Node.js version: node --version (must be 14+)

  • Ensure you have internet connection

  • Try clearing npm cache: npm cache clean --force

Credentials errors?

  • Verify your credentials are correct (check app.paywithlocus.com)

  • Make sure there are no extra spaces when pasting

  • Try creating new credentials if issues persist

App won't start?

  • Check the .env file was created correctly

  • Verify all required environment variables are set

  • Check the console for specific error messages

🎉 Congratulations! You're all set up and ready to build amazing things with Locus!

Start building AI agents with payment capabilities today.

PreviousIntroductionNextMCP Spec

Last updated