# Almond Settlement API

The Almond Settlement API enables clients to move funds cross-border by leveraging blockchain as the transfer layer.

As a client, you need to:

  - Authenticate to obtain an access token.
  - Check Settlement Rates for transparency.
  - Create a Settlement with relevant details.

Almond then fully automates the orchestration — buying crypto, transferring it across the blockchain, swapping it into destination currency, and depositing it into the recipient's  local bank account(or the account under the payout partner) — sending notifications upon successful completion.

<p align="center">
<img src="/images/settlement_flow_final.png" alt="System Flow" width="900"/><br>
<span style="font-size:0.9em;">Figure: Settlement Flow</span>
</p>


Version: 1.1.0
License: Copyright © 2025 Almond FinTech. All rights reserved.

## Servers

Sandbox
```
https://api.sandbox.almondfintech.com
```

Production
```
https://api.almondfintech.com
```

## Download OpenAPI description

[Almond Settlement API](https://almondfintechapi.redocly.app/_bundle/apis/settlements.yaml)

## Settlement Rate

### Get Settlement Rate

 - [GET /v2/settlement-rates](https://almondfintechapi.redocly.app/apis/settlements/settlement-rate/getsettlementrate.md): Retrieves the guaranteed/locked exchange rate for settlement along with forecast rates for different execution intervals.

Rate Information Includes:
- Current Rate: locked exchange rate for immediate execution
- Rate ID: Unique identifier of the rate
- Forecast Rates: Forecast rates for execution at different time intervals (1-6 hours)
- Corridor Information: Source and destination member IDs

Rate Locking:
- Each rate response includes a rateId that locks the current rate
- This rateId must be used when creating a settlement to guarantee the rate
- Rate locks have an expiry time (typically 15 minutes for immediate execution)

Forecast Rates:
- Provides rates for scheduled execution
- Available intervals: IMMEDIATE, ONE_HOUR, TWO_HOURS, THREE_HOURS, FOUR_HOURS, FIVE_HOURS, SIX_HOURS
- Helps members choose optimal execution timing based on rate forecasts

## Settlement Context

### Get Settlement Context

 - [GET /v2/settlement-context](https://almondfintechapi.redocly.app/apis/settlements/settlement-context/getsettlementcontext.md): Retrieves settlement context information, providing an overview of available settlement corridors and their current capacity.

This endpoint can be used to understand the following before creating settlements.
- Which destination members they can send settlements to
- Maximum settlement amounts allowed for each corridor
- Current settlement activity and capacity constraints:

## Settlement

### Create Settlement

 - [POST /v2/settlements](https://almondfintechapi.redocly.app/apis/settlements/settlement/createsettlement.md): Create a new settlement with the specified execution interval and locked rate.

Important Notes:
- Specified destinationMemberId must be a valid member ID that has an active corridor. Verify availability through /v2/settlement-context endpoint.
- Rate ID must be obtained from /v2/settlement-rates endpoint first
- Settlement amount cannot exceed the corridor's maximum limit available in /v2/settlement-context API

Execution Intervals:
- IMMEDIATE: Settlement executed as soon as possible (0 hours)
- ONE_HOUR to SIX_HOURS: Settlement scheduled for future execution

Settlement States After Creation:
- S100_SCHEDULED: If execution interval is in the future
- S200_RECEIVED: If immediate execution is requested

### Get Settlements

 - [GET /v2/settlements](https://almondfintechapi.redocly.app/apis/settlements/settlement/getsettlements.md): Retrieves a paginated list of settlements with optional filtering and sorting.

Available Filters:
- destinationMemberId: Filter by specific destination member
- settlementStatus: Filter by settlement status (S100_SCHEDULED, S200_RECEIVED, etc.)
- createdAfter: Filter settlements created after a specific date/time

Sorting Options:
- sortField: Field to sort by (creationTime, settlementAmt, rate, etc.)
- sortDirection: ASC (ascending) or DESC (descending)

Pagination:
- page: Page number (0-based)
- size: Number of records per page (default: 10)

Response includes:
- Array of settlement records
- Pagination metadata (totalPages, totalRecords)
- Settlement details for each record

### Get Settlement

 - [GET /v2/settlements/{settlement-id}](https://almondfintechapi.redocly.app/apis/settlements/settlement/getsettlement.md): Retrieves detailed information for a specific settlement by its unique identifier.

Response includes:
- Settlement details (amounts, rates, currencies, notes)
- Current status and timestamps
- Source and destination member information