The following are short articles on some general topics.
Pagination
To increase readability and optimize network traffic, some requests are returned with pagination, where 50 items are returned in a list. Use the limit query parameter to increase the number of items up to 100.
Asset Denomination
The API uses the minor units for all crypto assets. For example, ETH balances are given in Wei, BTC balances are given in satoshis, and SOL balances are given in Lamports. ERC20 token balances are given in the token's base units, and the asset info contains the number of decimals of the token. All values are represented as astring data type.
Fiat balances are also displayed in the minor unit of the currency. For example, USD amounts are given in cents.
API rate limits
Fordefi's API safeguards against bursts of incoming traffic to help maximize its stability for all users of the platform. Users who send many requests in quick succession might see error responses that show up as status code 429. The current number of requests per minute for each user is limited to 200.
Tip: Instead of polling, Fordefi recommends the use of webhooks to reduce calls to the Fordefi services.
Idempotent requests
Idempotency enables you to safely retry Create Transaction requests, while preventing inadvertent duplication of operations. This feature is most useful when a response is not received or when the initial API call did not complete successfully. Clients can make repeated identical calls, yielding the same outcome, as if they were making a single request.
- To perform an idempotent request, provide an additional
X-Idempotence-Id: <ID>header to the Create Transaction request. - To retrieve an idempotence ID, issue a call to List Transactions. The ID is located under
managed_transaction_data.
Fordefi's idempotency mechanism functions by storing the resulting status code and response body from the initial request made with a specific idempotency ID, regardless of whether the request was successful or not. Subsequent requests bearing the same ID will return identical results, complete with a 200 HTTP status code and the created transaction.
An idempotency ID is a unique value, generated programmatically by the client, which the server uses to recognize subsequent retries of the same request. While the method of generating unique IDs is at your discretion, they must be in UUID format. We recommend using V4 UUIDs. Fordefi checks that the IDs are valid. There is no defined maximum length for an ID.
Results are only retained if the /api/v1/transactions endpoint has commenced execution. If incoming parameters fail validation or if the request conflicts with another concurrent execution, no idempotent result is stored because no API endpoint has begun execution. In such cases, it is safe to retry these requests.