Bidding strategies

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.

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.

If none of these strategies fit your needs, there is support for external pricing logic. Contact us 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.

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.

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

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:

Asset-specific key — {SourceChain}->{DestChain}:{Asset} (e.g. Ethereum->Tron:USDC)
Chain-level key — {SourceChain}->{DestChain} (e.g. Ethereum->Tron)
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.

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.

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

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.

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.

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

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.

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.

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
Deploy and run the agent	Integration guide
Test pricing on testnet	Test a settlement flow

Overview

Start building

Settlement Reference

Bidding strategies

Overview

Choosing a strategy

Key concepts

Strategies

One To One

Static Markup

Corridor Based

Tiered

Spread Based

Additional considerations

Next steps

​Overview

​Choosing a strategy

​Key concepts

​Strategies

​One To One

​Static Markup

​Corridor Based

​Tiered

​Spread Based

​Additional considerations

​Next steps

Overview

Choosing a strategy

Key concepts

Strategies

One To One

Static Markup

Corridor Based

Tiered

Spread Based

Additional considerations

Next steps