Integration guide

Overview

Run a settlement agent on your own infrastructure, connect it to Atum’s network, and start potentially earning fees by fulfilling settlements. This guide covers a testnet deployment; the same flow applies to mainnet with production credentials and RPC endpoints.

Celo and Tron are used here as an example. Atum supports many additional EVM networks, plus Solana, with more chains on the way — see Supported mainnets.

You operate your own settler agent. You deploy, configure, and run it under your own infrastructure, credentials, keys, liquidity, pricing, and compliance controls. Atum provides the agent software and protocol interfaces; it does not run the agent for you or control your funds.

Authenticate and pull the image

Set up and configure

Run a setup script, then set your credentials and connection details.

Fund your wallets

Provide gas tokens and liquidity on each chain so the agent can transact.

Run the agent

Start the agent and confirm it connects to the gateway.

Prerequisites

Docker

Docker Engine installed and running on your host.

PostgreSQL 17

A PostgreSQL 17 database — managed (AWS RDS, GCP Cloud SQL) or self-hosted. Atum does not host databases for operators; you provision, maintain, and back up your own.

Temporal

A Temporal instance — managed or self-hosted — used for workflow orchestration. Atum does not host this for you.

Testnet wallets

An EVM wallet (Celo Sepolia) and/or a Tron wallet (Tron Shasta), each funded with testnet gas — see Fund your settler wallets.

Settler Gateway access

GATEWAY_ADDR is the Settler Gateway gRPC host (host:port), not the Payment Gateway HTTPS URL on Endpoints. Atum provisions the address and allowlists your organization and wallets. Email support@atum.xyz for access.

1. Authenticate to the container registry

The settler agent image is hosted on GitHub Container Registry. Authenticate before pulling.

Create a GitHub personal access token

GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic). Generate a token with the read:packages scope and copy it.

echo YOUR_GITHUB_PAT | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin

Verify access

docker pull ghcr.io/atum-labs/settler-agent:0.1.0

2. Set up the agent

Choose a setup approach. Each script pulls the image and generates configuration templates and a .env file.

Local
Cloud
Verify

Usually used for: development, testing, quick start.

./setup.sh

This pulls the image, creates configuration directories and templates, and generates a .env file. Then edit .env and start:

docker compose up -d

Uses Docker Compose with a local PostgreSQL container for quick testing.

Usually used for: production deployment on AWS, GCP, Azure, or Kubernetes.

./setup-cloud.sh

This pulls the image, creates a cloud-config/ directory with all templates, and prints recommended production resources.

Resource	Specification
CPU	6 vCPUs
Memory	24 GB
Instances	1 min, 20 max (auto-scaling)
Database	PostgreSQL 17, `db-perf-optimized-N-4` tier
Storage	100 GB SSD

For: confirming configuration is correct.

./test-setup.sh

Validates Docker image access, database connectivity, configuration file syntax, and environment variables.

3. Configure

After setup, edit .env with the essential variables:

ORGANIZATION=my-company
DATABASE_URL=postgresql://user:password@host:5432/settler_agent
GATEWAY_ADDR=<provided-by-atum>  # Settler Gateway gRPC host:port — not a Payment Gateway URL
NETWORK_ENV=testnet
CELO_PRIVATE_KEY=0x...
TRON_PRIVATE_KEY=...  # no 0x prefix for Tron

GATEWAY_ADDR is the Settler Gateway gRPC address Atum gives you. Do not paste a Payment Gateway URL from Endpoints.

Add .env to .gitignore and never commit it. Private keys control your liquidity.

For the full environment-variable reference, RPC configuration, and production settings, see Configuration. For production, use paid RPC providers rather than public endpoints, and consider using an MPC key management provider like Turnkey instead of plain text private key configurations.

4. Fund your settler wallets

Settler wallets need gas tokens to execute on-chain transactions.

Chain	Gas token	Minimum recommended
Celo Sepolia	CELO	1 CELO
Tron Shasta	TRX	100 TRX

For faucets and asset details, see Settlement testnets.

Without gas tokens, the agent connects to the gateway but fails when submitting transactions.

5. Run the agent

Docker Compose
Docker (manual)

# Initialize a fresh (empty) database
docker compose run --rm settler-agent migrate

# Start services
docker compose up -d

# View logs
docker compose logs -f settler-agent

# Run migrations
docker run --rm \
  -v $(pwd)/settler-config/profiles:/app/config/profiles \
  -v $(pwd)/settler-config/plugins/evm:/app/src/plugins/evm \
  -v $(pwd)/settler-config/plugins/tron:/app/src/plugins/tron \
  --env-file .env \
  --network host \
  ghcr.io/atum-labs/settler-agent:0.1.0 migrate

# Start agent
docker run -d \
  --name settler-agent \
  -v $(pwd)/settler-config/profiles:/app/config/profiles \
  -v $(pwd)/settler-config/plugins/evm:/app/src/plugins/evm \
  -v $(pwd)/settler-config/plugins/tron:/app/src/plugins/tron \
  --env-file .env \
  --network host \
  ghcr.io/atum-labs/settler-agent:0.1.0 start

Confirm the agent is healthy:

curl http://localhost:8080/health

Success criteria

Your agent is integrated when:

docker pull succeeds against ghcr.io/atum-labs/settler-agent
./test-setup.sh passes (image, database, config, env)
The agent starts and curl http://localhost:8080/health returns healthy
Logs show the agent connecting to the gateway and subscribing to payment requests

Next, run an end-to-end settlement — see Test a settlement flow.

Troubleshooting

Container won't start

Check logs: docker logs settler-agent. Common causes: missing environment variables, invalid configuration syntax, or expired Docker authentication.

Database connection failed

Verify DATABASE_URL format (postgresql://user:password@host:port/database), that the database is reachable from the container, that credentials are correct, and that PostgreSQL is version 17.

Gateway connection failed

Verify GATEWAY_ADDR (the Settler Gateway gRPC host:port Atum provided) and network connectivity. Email support@atum.xyz if the session handshake is refused — the gateway allowlists organization and wallets.

Transaction failures

Ensure wallets hold sufficient testnet gas, private keys are in the correct format (Celo with 0x, Tron without 0x), and RPC endpoints are responsive.

Private key format errors

Celo private keys include the 0x prefix (e.g. 0xabc123…); Tron private keys omit it (e.g. abc123…).

Next steps

Topic	Guide
Full configuration and RPC reference	Configuration
Diagnose a code in your agent’s logs	Agent error reference
Price and submit quotes on payments	Bidding strategies
Run an end-to-end settlement	Test a settlement flow
Testnet networks, assets, faucets	Settlement testnets
Talk through a large integration	Ask in Discord

Overview

Start building

Settlement Reference

Overview

Prerequisites

1. Authenticate to the container registry

2. Set up the agent

3. Configure

4. Fund your settler wallets

5. Run the agent

Success criteria

Troubleshooting

Next steps

​Overview

​Prerequisites

​1. Authenticate to the container registry

​2. Set up the agent

​3. Configure

​4. Fund your settler wallets

​5. Run the agent

​Success criteria

​Troubleshooting

​Next steps

Overview

Prerequisites

1. Authenticate to the container registry

2. Set up the agent

3. Configure

4. Fund your settler wallets

5. Run the agent

Success criteria

Troubleshooting

Next steps