Developer documentation
A small API. Clear contracts.
Use server-side keys, decimal-string amounts and an explicit reference or billing rate type.
1. Create a workspace key
Register through the IAMC-connected account form. In API keys, select read or quote access and download the credential once. Keep it in a server secret store, never frontend JavaScript.
2. Read and cache a snapshot
curl -H 'Authorization: Bearer YOUR_FLYMEBASE_KEY' \
'https://fx.vinexel.com/api/v1/fx/latest?kind=reference'Inspect source_date, fetched_at, stale, snapshot_id and the rates map inside the response data envelope. Daily snapshots are references, not live trade quotes.
3. Convert an amount
curl -X POST 'https://fx.vinexel.com/api/v1/fx/convert' \
-H 'Authorization: Bearer YOUR_FLYMEBASE_KEY' \
-H 'Content-Type: application/json' \
--data '{"amount":"12.50","from":"USD","to":"IDR","kind":"reference"}'Amounts are decimal strings. Output includes rate, rounded amount and snapshot. JPY, KRW and IDR use zero decimal places; other supported currencies use two. Rounding is half up.
Endpoints
Base URL: https://fx.vinexel.com. Send Authorization: Bearer YOUR_KEY with each API request.
| Method | Path and behavior | Scope |
|---|---|---|
| GET | /api/v1/fx/latest?kind=referenceLatest daily snapshot. kind=billing selects the operating USD/IDR policy. | fx.read |
| GET | /api/v1/fx/history?date=YYYY-MM-DDExact stored date, within plan history allowance. | fx.read |
| POST | /api/v1/fx/convertConvert without saving a quote. | fx.read |
| POST | /api/v1/fx/quotesSave evidence. Requires Idempotency-Key. | fx.quote |
| GET | /api/v1/fx/quotes/{quote_id}Read a quote owned by this API key. | fx.read |
Both rate kinds use USD as base. Reference conversions support currencies present in the snapshot; the current billing policy supports USD and IDR. History does not synthesize missing dates. The workspace dashboard can inspect all quotes owned by its workspace keys.
Immutable quotes and idempotency
POST /api/v1/fx/quotes
Authorization: Bearer YOUR_KEY
Idempotency-Key: invoice-2026-000001
Content-Type: application/json
{"amount":"3","from":"USD","to":"IDR","kind":"billing"}Reuse the same idempotency key and payload to replay the original quote. A changed payload returns 409. Observe expiry metadata: a quote is evidence, not payment authorization. Replaying still consumes an API request, but not another quote allowance.
Errors and limits
| HTTP | Meaning | Action |
|---|---|---|
| 400 | Invalid payload | Correct decimals, currencies or dates. |
| 403 | Key, scope, workspace or capacity denied | Review credentials and plan access. |
| 404 | Missing date or inaccessible quote | Use a stored date or owning key. |
| 409 | Idempotency conflict | Use the original payload or a new key. |
| 429 | Minute/month limit reached | Back off or review plan capacity. |
| 503 | Unavailable/stale source | Inspect source status; do not substitute billing silently. |
Valid-key admissions count toward shared UTC monthly requests, including downstream validation errors. There is no automatic overage charge. Cache complete snapshots. Activity metadata is retained for 90 days.
PHP transport SDK
The standalone client exposes latest, history, convert, quote and quote lookup. It carries your own key and never reads another project’s database. PHP cURL is required.
Download FxClient.php ↓require 'FxClient.php';
$client = new \Flymebase\Sdk\FxClient(
'https://fx.vinexel.com', getenv('FLYMEBASE_API_KEY'), 'development'
);
$snapshot = $client->latest('reference');Enterprise and service access
Enterprise capacity requires a separately agreed contract and administrator-recorded evidence. An operator provisions a fixed access period from workspace administration. Contract access is distinguished from payment and never treated as a free subscription.
Internal ecosystem services retain separate workload keys. Review public HTTPS origins, worker supervision, backups and payment callbacks before exposing a deployment commercially.
Source and security practices →