Settlement

Settlement modes

Mode	What happens
CUSTODIAL	Payment credits a platform ledger balance, then settles on-chain in batch (USDC / pathUSD).
DIRECT	Payment lands on-chain at the merchant’s own holder address in a registered project token (ERC-20, including B20). Requires an active Native Token Rails membership.

Set settlement_mode at credential issuance (POST /api/issue). It cannot be changed after creation. GET /api/pay/{code}/prepare and settle responses include settlement_mode so payers and agents know which path applies.

How custodial settlement works

When an agent makes a custodial payment, settlement is automatic:

Payment authorized: deducted from the card’s balance instantly
Queued for settlement: the transaction enters the settlement pipeline
Settled on-chain: USDC or pathUSD is transferred to the merchant
Confirmed: the transaction status is updated with the on-chain hash

Fees

Component	Amount
Platform fee	0.5% of transaction
Per-transaction fee	$0.001 (USDC/pathUSD)
On-chain gas	Covered by mag3nt

Example: A 10.00 token payment (USDC/pathUSD) costs 0.051 tokens: merchant receives 9.949 tokens.

Check settlement status

const status = await mag3nt.settlement.settlementGetStatus(transactionId);

console.log(status.settlement.status);     // PENDING | IN_PROGRESS | SETTLED | FAILED
console.log(status.settlement.feeAmount);  // 0.051
console.log(status.settlement.settledAt);  // 2026-05-21T00:30:00Z

Settlement states

Status	Description
`SANDBOX`	Testnet payment authorized. Not settled on-chain.
`PENDING`	Payment authorized, awaiting batch settlement
`IN_PROGRESS`	Settlement queued and actively being processed
`SETTLED`	On-chain transfer confirmed
`FAILED`	Settlement failed:funds returned to card

Timing

Authorization: Instant
Instant Settlement: Triggers immediately for network-fee efficient transactions.
Batch Settlement: Transactions that are not currently fee-efficient are grouped and settled rapidly in batches to optimize network costs.
On-chain confirmation: A few seconds on Base, Solana, and Tempo.

Custodial settlement runs automatically. You do not need to trigger it: check status when you need confirmation.

DIRECT settlement

DIRECT credentials do not use the custodial ledger for receives. Value is the on-chain balance of the funding asset at holder_address.

Membership quota meters DIRECT settles per calendar month (Membership).
Over-quota settles debit the prepaid MAG3NT fee meter (Fee meter).
Register the ERC-20 first (Project tokens).

If the plan is expired or quota is exhausted (and the fee meter cannot cover overage), DIRECT prepare/discover returns unavailable.

Getting Started

Core Concepts

Protocols Deep Dive

Agent Integration

SDKs

Settlement modes

How custodial settlement works

Fees

Check settlement status

Settlement states

Timing

DIRECT settlement

​Settlement modes

​How custodial settlement works

​Fees

​Check settlement status

​Settlement states

​Timing

​DIRECT settlement

Settlement modes

How custodial settlement works

Fees

Check settlement status

Settlement states

Timing

DIRECT settlement