# HercleX Execution API

> HercleX provides cross-border payment infrastructure with fiat/crypto rails, EU-licensed (CASP + EMI).

## Machine-Readable Resources

- [OpenAPI Spec (JSON)](https://documentation.hercle.financial/openapi.json)
- [Full API Reference (Markdown)](https://documentation.hercle.financial/llms-full.txt)
- [Endpoint Data (JSON)](https://documentation.hercle.financial/endpoint-data.json)

## Base URLs

- Sandbox: https://publicapi.sandbox.hercle.financial
- Production: https://publicapi.hercle.financial

## Authentication

Bearer token: `Authorization: Bearer YOUR_API_KEY`

## REST API Endpoints

- [Get Whitelisted Addresses](https://documentation.hercle.financial/api/addresses/get/): GET /api/v1/addresses/whitelisted
- [Whitelist Address](https://documentation.hercle.financial/api/addresses/create/): POST /api/v1/addresses/whitelist
- [Whitelist Address With Params](https://documentation.hercle.financial/api/addresses/params/): POST /api/v1/addresses/whitelist/params
- [Remove Whitelisted Address](https://documentation.hercle.financial/api/addresses/delete/): DELETE /api/v1/addresses/whitelist
- [Get Deposit Addresses](https://documentation.hercle.financial/api/addresses/deposit/): GET /api/v1/addresses/deposit
- [Create Deposit Address](https://documentation.hercle.financial/api/addresses/deposit-create/): POST /api/v1/addresses/deposit
- [Place OTC Order](https://documentation.hercle.financial/api/orders/get/): POST /api/v1/orders
- [Get Orders Paginated](https://documentation.hercle.financial/api/orders/list/): GET /api/v1/orders/{startDate}/{endDate}/{page}/{pageSize}
- [Get Orders by ClientId](https://documentation.hercle.financial/api/orders/client/): GET /api/v1/orders/{clientId}
- [Get Available Pairs](https://documentation.hercle.financial/api/pairs/get/): GET /api/v1/pairs
- [Get Pair Size by Amount](https://documentation.hercle.financial/api/pairs/size/): GET /api/v1/pairs/{pair}/{side}/{amount}
- [Get Asset Networks](https://documentation.hercle.financial/api/pairs/networks/): GET /api/v1/pairs/networks/{asset}
- [Get Pair Price](https://documentation.hercle.financial/api/pairs/price/): GET /api/v1/price/{pair}/{size}
- [Create RFQ](https://documentation.hercle.financial/api/rfq/create/): POST /api/v1/rfq
- [Accept RFQ](https://documentation.hercle.financial/api/rfq/accept/): POST /api/v1/rfq/accept
- [Create Custom RFQ](https://documentation.hercle.financial/api/rfq/custom-create/): POST /api/v1/rfq/custom-expiration
- [Get Balances](https://documentation.hercle.financial/api/user/balances/): GET /api/v1/user/balances
- [Get Trades Paginated](https://documentation.hercle.financial/api/user/trades/get/): GET /api/v1/user/trades/{startDate}/{endDate}/{page}/{pageSize}
- [Get Trades by ClientId](https://documentation.hercle.financial/api/user/trades/client/): GET /api/v1/user/trades/{tradeClientId}
- [Get Historical Trades Paginated](https://documentation.hercle.financial/api/user/trades/historical/): GET /api/v1/user/trades/{startDate}/{endDate}/{page}/{pageSize}/historical
- [Get Transactions Paginated](https://documentation.hercle.financial/api/user/transactions/): GET /api/v1/user/transactions/{startDate}/{endDate}/{page}/{pageSize}
- [Get Historical Transactions Paginated](https://documentation.hercle.financial/api/user/historical/transactions/): GET /api/v1/user/transactions/{startDate}/{endDate}/{page}/{pageSize}/historical
- [Create Withdrawal](https://documentation.hercle.financial/api/withdrawals/create/): POST /api/v1/withdrawals
- [Create Withdrawal With Address Params](https://documentation.hercle.financial/api/withdrawals/params/create/): POST /api/v1/withdrawals/address
- [Create Instant Withdrawal](https://documentation.hercle.financial/api/withdrawals/instant/create/): POST /api/v1/withdrawals/instant
- [Get Withdrawals](https://documentation.hercle.financial/api/withdrawals/get/): GET /api/v1/withdrawals
- [Get Withdrawals Paginated](https://documentation.hercle.financial/api/withdrawals/paginated/): GET /api/v1/withdrawals/{startDate}/{endDate}/{page}/{pageSize}
- [Get Withdrawals by ClientId](https://documentation.hercle.financial/api/withdrawals/clientId/): GET /api/v1/withdrawals/{withdrawClientId}
- [Get Business End Users Paginated](https://documentation.hercle.financial/api/banking/business-end-users/get/): GET /api/v1/end-users/businesses?pageSize={pageSize}
- [Register Business End User](https://documentation.hercle.financial/api/banking/business-end-users/register/): POST /api/v1/end-users/businesses
- [Get Individual End Users Paginated](https://documentation.hercle.financial/api/banking/individual-end-users/get/): GET /api/v1/end-users/individuals?pageSize={pageSize}
- [Register Individual End User](https://documentation.hercle.financial/api/banking/individual-end-users/register/): POST /api/v1/end-users/individuals
- [Get Deposit Accounts Paginated](https://documentation.hercle.financial/api/banking/deposit-accounts/get/): GET /api/v1/deposit-accounts?pageSize={pageSize}
- [Create Deposit Account](https://documentation.hercle.financial/api/banking/deposit-accounts/create/): POST /api/v1/deposit-accounts
- [Get Payees Paginated](https://documentation.hercle.financial/api/banking/payee/get/): GET /api/v1/payees?pageSize={pageSize}
- [Register Payee](https://documentation.hercle.financial/api/banking/payee/create/): POST /api/v1/payee
- [Get Payee Addresses Paginated](https://documentation.hercle.financial/api/banking/payee/addresses/get/): GET /api/v1/payee-addresses?payeeId={payeeId}&pageSize={pageSize}
- [Register Payee Address](https://documentation.hercle.financial/api/banking/payee/address/create/): POST /api/v1/payees/{payeeId}/addresses
- [Approve Payee Address](https://documentation.hercle.financial/api/banking/payee/address/approve/): PATCH /api/v1/payees/{payeeId}/addresses/{payeeAddressId}/approve
- [Get Transfers Paginated](https://documentation.hercle.financial/api/banking/transfers/get/): GET /api/v1/transfers?startDate={startDate}&endDate={endDate}&pageSize={pageSize}
- [Create Transfer](https://documentation.hercle.financial/api/banking/transfers/create/): POST /api/v1/transfer
- [Get Transaction Ledger](https://documentation.hercle.financial/api/banking/ledger/get/): GET /api/v1/transactions/{transactionId}
- [Simulate Pay-In](https://documentation.hercle.financial/api/banking/simulate-payin/): POST /api/v1/simulate-payin
- [Create Lightning Invoice](https://documentation.hercle.financial/api/invoices/create/): POST /api/v1/invoices
- [Get Lightning Invoices](https://documentation.hercle.financial/api/invoices/get/): GET /api/v1/invoices
- [Create Lightning Withdrawal](https://documentation.hercle.financial/api/lightning/withdrawals/create/): POST /api/v1/lightning/withdrawals

## WebSocket Commands (SignalR)

- [Get Available Pairs](https://documentation.hercle.financial/ws/get-pairs/): GetPairs
- [Get Asset Networks](https://documentation.hercle.financial/ws/get-asset-networks/): GetNetworks
- [Get Pair Size by Amount](https://documentation.hercle.financial/ws/get-pair-size-by-amount/): GetPairSizeByAmount
- [Pair Price Stream](https://documentation.hercle.financial/ws/pair-price-stream/): SubscribePairPriceChannel
- [Place OTC Order](https://documentation.hercle.financial/ws/place-otc-order/): PlaceOtcOrder
- [Get Orders Paginated](https://documentation.hercle.financial/ws/get-orders-paginated/): GetOrdersPaginated
- [Get Orders By Client ID](https://documentation.hercle.financial/ws/get-orders-by-client-id/): GetOrdersByClientId
- [Create RFQ](https://documentation.hercle.financial/ws/create-rfq/): CreateRequestForQuote
- [Create Custom RFQ](https://documentation.hercle.financial/ws/create-custom-rfq/): CreateRequestForQuoteWithCustomExpiration
- [Accept RFQ](https://documentation.hercle.financial/ws/accept-rfq/): AcceptRequestForQuote
- [Get Transactions Paginated](https://documentation.hercle.financial/ws/get-transactions-paginated/): GetTransactionsPaginated
- [Get Historical Transactions Paginated](https://documentation.hercle.financial/ws/get-historical-transactions-paginated/): GetHistoricalTransactionsPaginated
- [Get Trades Paginated](https://documentation.hercle.financial/ws/get-trades-paginated/): GetTradesPaginated
- [Get Historical Trades Paginated](https://documentation.hercle.financial/ws/get-historical-trades-paginated/): GetHistoricalTradesPaginated
- [Get Trades By Client ID](https://documentation.hercle.financial/ws/get-trades-by-client-id/): GetTradesByClientId
- [Get Balances](https://documentation.hercle.financial/ws/get-balances/): GetBalances
- [Create Withdraw](https://documentation.hercle.financial/ws/create-withdraw/): WithdrawFunds
- [Create Withdraw with Address Params](https://documentation.hercle.financial/ws/create-withdraw-with-params/): WithdrawFundsWithAddressParams
- [Create Instant Withdrawal](https://documentation.hercle.financial/ws/create-instant-withdraw/): WithdrawInstantFunds
- [Get Withdrawals](https://documentation.hercle.financial/ws/get-withdrawals/): GetWithdrawals
- [Get Withdrawals Paginated](https://documentation.hercle.financial/ws/get-withdrawals-paginated/): GetWithdrawalsPaginated
- [Get Withdrawals by ClientId](https://documentation.hercle.financial/ws/get-withdrawals-by-client-id/): GetWithdrawalsByClientId
- [Get Whitelisted Addresses](https://documentation.hercle.financial/ws/get-whitelisted-addresses/): GetWhitelistedAddresses
- [Whitelist Address](https://documentation.hercle.financial/ws/create-whitelisted-address/): WhitelistAddress
- [Whitelist Address with Params](https://documentation.hercle.financial/ws/create-whitelisted-address-with-params/): WhitelistAddressWithParams
- [Remove Whitelisted Address](https://documentation.hercle.financial/ws/remove-whitelisted-address/): DeleteWhitelistedAddress
- [Get Deposit Addresses](https://documentation.hercle.financial/ws/get-deposit-addresses/): GetDepositAddress
- [Create Deposit Address](https://documentation.hercle.financial/ws/create-deposit-address/): CreateDepositAddress
- [Create Deposit](https://documentation.hercle.financial/ws/create-deposit/): CreateDeposit
- [Get Payees Paginated](https://documentation.hercle.financial/ws/get-payees/): GetPayeesPaginated
- [Register Payee](https://documentation.hercle.financial/ws/create-payee/): RegisterPayee
- [Get Payee Addresses Paginated](https://documentation.hercle.financial/ws/get-payee-addresses/): GetPayeeAddressesPaginated
- [Register Payee Address](https://documentation.hercle.financial/ws/create-payee-address/): RegisterPayeeAddress
- [Get Transfers Paginated](https://documentation.hercle.financial/ws/get-transfers/): GetTransfersPaginated
- [Create Transfer](https://documentation.hercle.financial/ws/create-transfer/): TransferFunds
- [Get Transaction Ledger](https://documentation.hercle.financial/ws/get-ledger/): GetTransactionLedger
- [Create Lightning Invoice](https://documentation.hercle.financial/ws/create-lightning-invoice/): CreateLightningInvoice
- [Get Lightning Invoices](https://documentation.hercle.financial/ws/get-lightning-invoices/): GetLightningInvoices
- [Create Lightning Withdrawal](https://documentation.hercle.financial/ws/withdraw-lightning/): WithdrawLightning

## Common Patterns

- **Idempotency**: Use Client-Id header on POST endpoints. 6-hour TTL.
- **Webhooks**: POST to your URL with HMAC-SHA256 signature in X-Hercle-Signature header.
- **Status codes**: 200 (success), 201 (created), 400 (bad request), 401 (unauthorized), 429 (rate limited).