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

# Bidding strategies

> Configure how a settler agent prices and submits quotes to payment requests.

## Overview

When the gateway broadcasts a payment request, the settler agent decides whether to provide a quote and at what price. The **bidding strategy** determines how the agent calculates the `source_amount` (what the sender pays) from the `fulfillment_amount` (what the recipient receives).

Pricing is fully operator-controlled. Choose the strategy that matches your pricing model and risk posture, then tune it per corridor as you learn where you might be successful.

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

If none of these strategies fit your needs, there is support for external pricing logic. [Contact us](mailto:support@atum.xyz) for more information.

## Choosing a strategy

| Strategy        | Often used for                | Complexity | Predictability |
| --------------- | ----------------------------- | ---------- | -------------- |
| `oneToOne`      | Testing, promotions           | Low        | High           |
| `staticMarkup`  | Simple operations             | Low        | High           |
| `corridorBased` | Multi-rail with varying costs | Medium     | High           |
| `tiered`        | Volume incentives             | Medium     | High           |
| `spreadBased`   | Competitive markets           | High       | Low            |

## Key concepts

| Term                 | Meaning                                                                 |
| -------------------- | ----------------------------------------------------------------------- |
| `fulfillment_amount` | The amount the recipient receives on the destination chain.             |
| `source_amount`      | The amount the agent quotes — what the sender pays on the source chain. |
| `max_source_amount`  | The most the sender is willing to pay.                                  |
| `markupBps`          | Markup in basis points (1 bps = 0.01%, 100 bps = 1%).                   |

## Strategies

### One To One

Quotes the `fulfillment_amount` as the `source_amount` — 1:1 pricing with no markup.

**Often used for:** testing, promotional periods, or offering zero-fee transfers.

```yaml theme={null}
execution:
  bidding:
    strategy: oneToOne
    oneToOne: {} # no configuration options
```

```
source_amount = fulfillment_amount
```

| fulfillment\_amount | max\_source\_amount | source\_amount | Result                  |
| ------------------- | ------------------- | -------------- | ----------------------- |
| 100 USDC            | 105 USDC            | 100 USDC       | ✅ Bid submitted         |
| 100 USDC            | 99 USDC             | 100 USDC       | ❌ Skipped (exceeds max) |
| 100 USDC            | (none)              | 100 USDC       | ✅ Bid submitted         |

***

### Static Markup

Applies a fixed percentage markup plus an optional flat fee to every payment.

**Often used for:** simple, predictable pricing across all corridors and sizes.

```yaml theme={null}
execution:
  bidding:
    strategy: staticMarkup
    staticMarkup:
      markupBps: 50 # 0.5% markup
      markupAbsolute: '0' # optional flat fee
```

```
percentage_markup = fulfillment_amount × (markupBps / 10000)
source_amount = fulfillment_amount + percentage_markup + markupAbsolute
```

**Example** (`markupBps: 50`, `markupAbsolute: '100000'`):

| fulfillment\_amount       | Percentage (0.5%) | Absolute | source\_amount | max\_source\_amount | Result                  |
| ------------------------- | ----------------- | -------- | -------------- | ------------------- | ----------------------- |
| 100,000,000 (100 USDC)    | 500,000           | 100,000  | 100,600,000    | 101,000,000         | ✅ Bid submitted         |
| 100,000,000 (100 USDC)    | 500,000           | 100,000  | 100,600,000    | 100,500,000         | ❌ Skipped (exceeds max) |
| 1,000,000,000 (1000 USDC) | 5,000,000         | 100,000  | 1,005,100,000  | (none)              | ✅ Bid submitted         |

***

### Corridor Based

Different markups for different source→destination combinations, with optional asset-specific overrides.

**Often used for:** when costs vary by corridor (e.g. Ethereum→Tron differs from Tron→Ethereum on gas).

```yaml theme={null}
execution:
  bidding:
    strategy: corridorBased
    corridorBased:
      default:
        markupBps: 50
        markupAbsolute: '0'
      corridors:
        # Chain-level override
        'Ethereum->Tron':
          markupBps: 30
        # Asset-specific override (higher priority)
        'Ethereum->Tron:USDC':
          markupBps: 25
          markupAbsolute: '50000'
        'Tron->Ethereum':
          markupBps: 75
```

**Lookup priority:**

1. Asset-specific key — `{SourceChain}->{DestChain}:{Asset}` (e.g. `Ethereum->Tron:USDC`)
2. Chain-level key — `{SourceChain}->{DestChain}` (e.g. `Ethereum->Tron`)
3. Default config

| Corridor      | Asset | Markup used      | fulfillment\_amount | source\_amount |
| ------------- | ----- | ---------------- | ------------------- | -------------- |
| Ethereum→Tron | USDC  | 25 bps + 50000   | 100,000,000         | 100,300,000    |
| Ethereum→Tron | USDT  | 30 bps           | 100,000,000         | 100,300,000    |
| Tron→Ethereum | USDC  | 75 bps           | 100,000,000         | 100,750,000    |
| Arbitrum→Celo | USDC  | 50 bps (default) | 100,000,000         | 100,500,000    |

***

### Tiered

Volume-based pricing where markup varies by payment size. Smaller payments pay a higher percentage; larger payments get better rates.

**Often used for:** incentivizing larger payments while staying profitable on small ones.

```yaml theme={null}
execution:
  bidding:
    strategy: tiered
    tiered:
      tiers:
        - minAmount: '0'
          maxAmount: '100000000' # < 100 USDC
          markupBps: 150 # 1.5%
        - minAmount: '100000000'
          maxAmount: '1000000000' # 100–1000 USDC
          markupBps: 75 # 0.75%
        - minAmount: '1000000000'
          maxAmount: null # ≥ 1000 USDC (null = unlimited)
          markupBps: 25 # 0.25%
      fallbackMarkupBps: 100 # used if no tier matches (optional)
```

**Tier matching:**

* Tiers are evaluated in order
* A tier matches when `minAmount <= fulfillment_amount < maxAmount`
* `maxAmount: null` means no upper limit
* If no tier matches, `fallbackMarkupBps` is used (when configured)

| fulfillment\_amount       | Tier     | markupBps | source\_amount |
| ------------------------- | -------- | --------- | -------------- |
| 50,000,000 (50 USDC)      | \< 100   | 150       | 50,750,000     |
| 100,000,000 (100 USDC)    | 100–1000 | 75        | 100,750,000    |
| 500,000,000 (500 USDC)    | 100–1000 | 75        | 503,750,000    |
| 5,000,000,000 (5000 USDC) | ≥ 1000   | 25        | 5,012,500,000  |

***

### Spread Based

Captures a percentage of the spread between `fulfillment_amount` and `max_source_amount`. Prices against what the sender is willing to pay rather than a fixed markup.

**Often used for:** competitive markets where you want to capture value while still beating the sender's maximum.

```yaml theme={null}
execution:
  bidding:
    strategy: spreadBased
    spreadBased:
      spreadCapturePct: 50 # capture 50% of available spread
      minMarkupBps: 10 # floor: at least 0.1% markup (optional)
      maxMarkupBps: 200 # ceiling: at most 2% markup (optional)
```

```
spread = max_source_amount - fulfillment_amount
captured_spread = spread × (spreadCapturePct / 100)
source_amount = fulfillment_amount + captured_spread

# Apply constraints
if source_amount < fulfillment_amount × (1 + minMarkupBps/10000):
    source_amount = fulfillment_amount × (1 + minMarkupBps/10000)
if source_amount > fulfillment_amount × (1 + maxMarkupBps/10000):
    source_amount = fulfillment_amount × (1 + maxMarkupBps/10000)
if source_amount > max_source_amount:
    source_amount = max_source_amount
```

**Special cases:**

* If `max_source_amount` is absent, the agent uses `minMarkupBps` as the markup
* If the spread is zero or negative, the bid is skipped

**Example** (`spreadCapturePct: 50`, `minMarkupBps: 10`, `maxMarkupBps: 200`):

| fulfillment\_amount | max\_source\_amount | Spread     | 50% capture | Constraints      | source\_amount |
| ------------------- | ------------------- | ---------- | ----------- | ---------------- | -------------- |
| 100,000,000         | 102,000,000         | 2,000,000  | 1,000,000   | 1% markup OK     | 101,000,000    |
| 100,000,000         | 100,050,000         | 50,000     | 25,000      | Below min (0.1%) | 100,100,000    |
| 100,000,000         | 110,000,000         | 10,000,000 | 5,000,000   | Above max (2%)   | 102,000,000    |
| 100,000,000         | 100,000,000         | 0          | —           | No spread        | ❌ Skipped      |
| 100,000,000         | (none)              | —          | —           | Use minMarkupBps | 100,100,000    |

## Additional considerations

<AccordionGroup>
  <Accordion title="Start conservative">
    Consider whether it might be prudent to begin with higher markups on testnet to confirm profitability, then lower them based on competition and performance data.
  </Accordion>

  <Accordion title="Account for gas costs">
    Chains differ in gas costs. Consider using `corridorBased` to reflect this — higher markups on high-gas chains, lower on low-gas chains.
  </Accordion>

  <Accordion title="Monitor win rate">
    Track win rate and adjust:

    * **High win rate** → potentially consider lowering markups to grow volume
    * **Low win rate** → consider whether pricing may be too high
  </Accordion>

  <Accordion title="Use tiered for volume">
    To potentially attract larger payments, consider whether it may be prudent to set lower rates for high volumes, and whether it may be useful for capturing institutional-sized flow.
  </Accordion>

  <Accordion title="Use spreadBased for a competitive edge">
    In challenging markets, `spreadBased` may potentially keep quotes competitive relative to the sender's willingness to pay, and might potentially increase bid selection.
  </Accordion>
</AccordionGroup>

**NOTE:**

None of the bidding options constitute a representation, warranty, or guarantee of profitability or any returns, and settlement operators may incur losses in connection with settlement activity, including but not limited to losses arising from market conditions, execution dynamics, pricing constraints, or third-party costs (e.g., blockchain gas fees, bridge fees, validator fees, fiat payout fees, bank fees, FX spreads, or other protocol-level costs or similar expenses).

## Next steps

| Topic                        | Guide                                                    |
| ---------------------------- | -------------------------------------------------------- |
| Full configuration reference | [Configuration](/settle-payments/configuration/overview) |
| Deploy and run the agent     | [Integration guide](/settle-payments/integration-guide)  |
| Test pricing on testnet      | [Test a settlement flow](/settle-payments/testnet)       |