> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atum.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration guide

> Deploy and run a settler agent on your own infrastructure.

## 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.

<Note>
  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](/settle-payments/supported-mainnets).
</Note>

<Info>
  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.
</Info>

<Steps>
  <Step title="Authenticate and pull the image">Sign in to the container registry and pull the settler agent.</Step>
  <Step title="Set up and configure">Run a setup script, then set your credentials and connection details.</Step>
  <Step title="Fund your wallets">Provide gas tokens and liquidity on each chain so the agent can transact.</Step>
  <Step title="Run the agent">Start the agent and confirm it connects to the gateway.</Step>
</Steps>

## Prerequisites

<AccordionGroup>
  <Accordion title="Docker">
    Docker Engine installed and running on your host.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Temporal">
    A Temporal instance — managed or self-hosted — used for workflow orchestration. Atum does not host this for you.
  </Accordion>

  <Accordion title="Testnet wallets">
    An EVM wallet (Celo Sepolia) and/or a Tron wallet (Tron Shasta), each funded with testnet gas — see [Fund your settler wallets](#4-fund-your-settler-wallets).
  </Accordion>

  <Accordion title="Settler Gateway access">
    `GATEWAY_ADDR` is the Settler Gateway gRPC host (`host:port`), not the Payment Gateway HTTPS URL on [Endpoints](/get-started/reference/endpoints). Atum provisions the address and allowlists your organization and wallets. Email [support@atum.xyz](mailto:support@atum.xyz) for access.
  </Accordion>
</AccordionGroup>

## 1. Authenticate to the container registry

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Log in to the registry">
    ```bash theme={null}
    echo YOUR_GITHUB_PAT | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
    ```
  </Step>

  <Step title="Verify access">
    ```bash theme={null}
    docker pull ghcr.io/atum-labs/settler-agent:0.1.0
    ```
  </Step>
</Steps>

## 2. Set up the agent

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

<Tabs>
  <Tab title="Local">
    **Usually used for:** development, testing, quick start.

    ```bash theme={null}
    ./setup.sh
    ```

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

    ```bash theme={null}
    docker compose up -d
    ```

    <Info>Uses Docker Compose with a local PostgreSQL container for quick testing.</Info>
  </Tab>

  <Tab title="Cloud">
    **Usually used for:** production deployment on AWS, GCP, Azure, or Kubernetes.

    ```bash theme={null}
    ./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                                  |
  </Tab>

  <Tab title="Verify">
    **For:** confirming configuration is correct.

    ```bash theme={null}
    ./test-setup.sh
    ```

    Validates Docker image access, database connectivity, configuration file syntax, and environment variables.
  </Tab>
</Tabs>

## 3. Configure

After setup, edit `.env` with the essential variables:

```env theme={null}
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
```

<Note>
  `GATEWAY_ADDR` is the Settler Gateway gRPC address Atum gives you. Do not paste a Payment Gateway URL from [Endpoints](/get-started/reference/endpoints).
</Note>

<Warning>
  Add `.env` to `.gitignore` and never commit it. Private keys control your liquidity.
</Warning>

<Info>
  For the full environment-variable reference, RPC configuration, and production settings, see [Configuration](/settle-payments/configuration/overview). 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.
</Info>

## 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](/settle-payments/supported-testnets).

<Info>
  Without gas tokens, the agent connects to the gateway but fails when submitting transactions.
</Info>

## 5. Run the agent

<Tabs>
  <Tab title="Docker Compose">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Docker (manual)">
    ```bash theme={null}
    # 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
    ```
  </Tab>
</Tabs>

Confirm the agent is healthy:

```bash theme={null}
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](/settle-payments/testnet).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Container won't start">
    Check logs: `docker logs settler-agent`. Common causes: missing environment variables, invalid configuration syntax, or expired Docker authentication.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Gateway connection failed">
    Verify `GATEWAY_ADDR` (the Settler Gateway gRPC `host:port` Atum provided) and network connectivity. Email [support@atum.xyz](mailto:support@atum.xyz) if the session handshake is refused — the gateway allowlists organization and wallets.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Private key format errors">
    Celo private keys include the `0x` prefix (e.g. `0xabc123…`); Tron private keys omit it (e.g. `abc123…`).
  </Accordion>
</AccordionGroup>

## Next steps

| Topic                                | Guide                                                      |
| ------------------------------------ | ---------------------------------------------------------- |
| Full configuration and RPC reference | [Configuration](/settle-payments/configuration/overview)   |
| Diagnose a code in your agent's logs | [Agent error reference](/settle-payments/error-reference)  |
| Price and submit quotes on payments  | [Bidding strategies](/settle-payments/bidding-strategies)  |
| Run an end-to-end settlement         | [Test a settlement flow](/settle-payments/testnet)         |
| Testnet networks, assets, faucets    | [Settlement testnets](/settle-payments/supported-testnets) |
| Talk through a large integration     | [Ask in Discord](https://discord.gg/a5mbNjnDNj)            |