> ## Documentation Index
> Fetch the complete documentation index at: https://x402-stellar.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Contract Interface Reference

> Public functions, error codes, and storage keys for settlement-verifier

## Public Functions

### `initialize`

Initializes contract state. Can only be invoked once.

```rust theme={null}
pub fn initialize(
    env: Env,
    admin: Address,
    fee_recipient: Address,
    fee_bps: u32
) -> Result<(), Error>
```

* `admin`: Account authorized to update fee configs and protocol settings.
* `fee_recipient`: Account that collects basis point protocol fees.
* `fee_bps`: Protocol fee in basis points (max `1,000` = 10%).

***

### `settle_payment`

Executes an atomic transfer from payer to merchant, deducting the protocol fee.

```rust theme={null}
pub fn settle_payment(
    env: Env,
    payer: Address,
    merchant: Address,
    token: Address,
    amount: i128,
    nonce: u64,
    valid_until: u64
) -> Result<i128, Error>
```

* Reverts with `Error::InvalidNonce` if `nonce != current_nonce + 1`.
* Reverts with `Error::ExpiredSignature` if `env.ledger().timestamp() > valid_until`.
* Invokes `token::Client::new(&env, &token).transfer(...)` atomically.
* Emits `SettlementReceipt` event.
* Returns the net amount transferred to the merchant (`i128`).

***

### `verify_and_split`

Splits a payment across multiple recipients according to basis points.

```rust theme={null}
pub fn verify_and_split(
    env: Env,
    payer: Address,
    token: Address,
    amount: i128,
    recipients: Vec<(Address, u32)>,
    nonce: u64
) -> Result<(), Error>
```

* Enforces that the sum of recipient basis points plus protocol fee equals `10,000` (100%).
* Atomically transfers each recipient's share.

***

### Read Views

```rust theme={null}
pub fn get_nonce(env: Env, account: Address) -> u64
pub fn get_admin(env: Env) -> Address
pub fn get_fee_config(env: Env) -> (u32, Address)
```

***

## Error Codes (`#[contracterror]`)

| Code | Variant              | Reason                                                    |
| ---- | -------------------- | --------------------------------------------------------- |
| `1`  | `AlreadyInitialized` | Attempted to re-initialize an already configured contract |
| `2`  | `NotInitialized`     | Function called before contract initialization            |
| `3`  | `Unauthorized`       | Caller lacks admin authorization                          |
| `4`  | `InvalidNonce`       | Payer nonce did not match expected monotonic value        |
| `5`  | `ExpiredSignature`   | Current ledger timestamp exceeds `valid_until`            |
| `6`  | `InvalidAmount`      | Payment amount is zero or negative                        |
| `7`  | `InvalidFeeBps`      | Fee BPS exceeds maximum allowed threshold                 |
| `8`  | `TransferFailed`     | Underlying Stellar Asset Contract transfer failed         |