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

# API Overview

> Authenticate, handle errors, and understand rate limits for the Orchestra REST API at orchestration.flashnet.xyz.

Base URL: `https://orchestration.flashnet.xyz`

OpenAPI:

* Swagger UI: `GET /docs`
* OpenAPI JSON: `GET /openapi.json`

Orchestra is the product name. API paths use the `/v1/orchestration/` prefix.

The OpenAPI spec omits `GET /v1/orchestration/estimate`. This endpoint is documented below under Authentication and in the Rate Limiting table.

Start here:

* Product overview: [Orchestra](/products/orchestration/overview)
* End-to-end integration flow: [Quickstart](/products/orchestration/integration)

## How does authentication work?

Authenticated endpoints require an API key:

```bash theme={null}
Authorization: Bearer fn_...    # server key (secret)
Authorization: Bearer fnp_...   # client key (public, scoped)
```

Use `GET /v1/orchestration/estimate` for unauthenticated price previews.

`POST /v1/orchestration/quote` is the start of a submit-able flow and should be called with `Authorization`. Quotes created without `Authorization` (if accepted) cannot be submitted.

A quote is bound to your partner account and can only be submitted by an API key for the same partner.

If a quote uses `affiliateId` or `affiliateIds`, `Authorization` is required because affiliate profiles are partner-scoped.

### Server keys vs client keys

Orchestra issues two key types. Server keys (`fn_...`) are secret and have full access. Client keys (`fnp_...`) are public, scope-gated, and safe to embed in open-source SDKs or browser code.

Use a server key when the key runs in an environment you control. Use a client key when the key will ship inside something your users can inspect. See [Client Keys](/products/orchestration/api/client-keys) for scopes, modes, read-tokens, and rate limits.

## How does idempotency work?

Partner-authenticated mutating endpoints require `X-Idempotency-Key`.

Rules:

* Key scope is `(partnerId, endpoint, key)`.
* Replaying the same request returns the stored response and sets `X-Idempotency-Replayed: true`.
* Reusing a key with a different JSON body returns `409 idempotency_conflict`.

## Errors

Errors use a single envelope:

```json theme={null}
{
  "error": {
    "code": "string",
    "message": "string"
  }
}
```

Common `error.code` values:

* `unauthorized`: Missing or invalid API key
* `auth_required`: Authentication is required for this request
* `forbidden`: Route or action is not permitted for the key type presented (typically a client key hitting a server-only endpoint)
* `origin_required`: Client key in `browser` mode is missing the `Origin` header
* `origin_not_allowed`: Origin is not on the key's allowed list
* `read_token_required`: Client key hit `GET /v1/orchestration/status` or SSE without `X-Read-Token` / `?readToken=`
* `invalid_read_token`: Read-token is malformed, expired, or not bound to this order / key
* `missing_idempotency_key`: `X-Idempotency-Key` missing
* `idempotency_conflict`: Same idempotency key reused with a different payload
* `unsupported_route`: Route is not supported
* `unsupported_amount_mode`: `amountMode` is not supported for the selected route
* `unsupported_fee_plan`: `appFees`, `affiliateId`, or `affiliateIds` is not supported for the selected route or quote mode
* `invalid_request`: Request body failed business validation
* `invalid_query`: Invalid query parameters
* `invalid_address`: Recipient or refund address is invalid
* `invalid_state`: Endpoint was called in the wrong order state
* `conflict`: State changed concurrently, retry the request
* `quote_expired`: Quote has expired
* `not_found`: Quote or order not found
* `amount_too_small`: Swap input is below the Flashnet pool minimum
* `amount_too_large`: Amount is too large for the selected route
* `rate_limited`: Too many requests
* `flashnet_error`: Swap simulation or execution failed
* `price_impact_too_high`: Quote exceeds configured price impact constraints
* `internal_error`: Unhandled error

Some malformed JSON or schema violations currently surface as `internal_error`. Treat it as a request bug and retry only after fixing the payload.

## What chains, assets, and amount formats are supported?

Routes are expressed as `(sourceChain, sourceAsset) -> (destinationChain, destinationAsset)`.

Supported chains:

* `base`
* `solana`
* `ethereum`
* `arbitrum`
* `optimism`
* `polygon`
* `bsc`
* `tempo`
* `tron`
* `plasma`
* `monad`
* `spark`
* `bitcoin`
* `lightning`

Supported assets:

* `USDC`
* `USDC.e`
* `USDT`
* `PathUSD`
* `USDB`
* `BTC`
* `ETH`
* `SOL`
* `BNB`
* `DAI`
* `WBTC`
* `cbBTC`

Tempo `USDC` is supported as both a source and destination asset. Tempo `PathUSD` is currently supported as a destination asset. `WBTC` and `DAI` are available on Ethereum. `cbBTC` is available on Base, Solana, and Monad. `BNB` and `USDT` are available on BSC. `USDC.e` is available on Polygon. Monad supports `USDC` and `cbBTC`.

Amounts are integer strings in smallest units. Do not send floats.

## Rate limiting

Some public endpoints are IP rate-limited when rate limiting is enabled in the deployment:

* `GET /v1/orchestration/routes`: 60 requests per minute
* `GET /v1/orchestration/estimate`: 120 requests per minute
* `POST /v1/orchestration/quote`: 60 requests per minute
* `GET /v1/orchestration/order`: 120 requests per minute
* `GET /v1/orchestration/status`: 120 requests per minute

When enabled, responses include `X-RateLimit-*` headers and the API returns `429 rate_limited` on exhaustion.

Client keys have an additional two-layer rate limit that server keys don't:

| Route                             | Per-key/min | Per-(key, IP)/min |
| --------------------------------- | ----------- | ----------------- |
| `POST /v1/orchestration/quote`    | 600         | 60                |
| `POST /v1/orchestration/submit`   | 120         | 10                |
| `POST /v1/orchestration/onramp`   | 120         | 10                |
| `POST /v1/accumulation-addresses` | 60          | 5                 |
| `POST /v1/liquidation-addresses`  | 60          | 5                 |

See [Client Keys](/products/orchestration/api/client-keys) for the full model.

## Reference pages

* [Client Keys](/products/orchestration/api/client-keys): Public, scope-gated keys for SDK and browser embedding
* [Quotes and Orders](/products/orchestration/api/quotes-and-orders): Create quotes, submit deposits, and track order status
* [Approval Flows](/products/orchestration/api/approval-flows): Resolve repricing requests and ZeroConf offers
* [Resource Management](/products/orchestration/api/resources): Manage affiliates, webhooks, accumulation addresses, and liquidation addresses