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

# Settlement

> How payments settle on-chain: custodial batch settlement and DIRECT (non-custodial) project-token rails.

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

1. **Payment authorized**: deducted from the card's balance instantly
2. **Queued for settlement**: the transaction enters the settlement pipeline
3. **Settled on-chain**: USDC or pathUSD is transferred to the merchant
4. **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

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

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

## 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](/concepts/membership)).
* Over-quota settles debit the prepaid MAG3NT fee meter ([Fee meter](/concepts/fee-meter)).
* Register the ERC-20 first ([Project tokens](/concepts/project-tokens)).

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