BluebulbAPI
    API reference/Conversions
    POST

    Create a conversion

    POST{baseUrl}/api/conversions

    Converts funds between two of your currency balances. The source amount is debited immediately and the conversion completes in the background.

    Authentication

    Send your API key and a request signature on every call. Requests must also come from an IP address on your allowlist — see Authentication.

    Headers

    x-api-key
    required
    string
    Your API key, <appId>.<secret>. See Authentication.
    X-Signature
    required
    string
    Base64 RSA-SHA256 signature of the request. See Request signing.
    X-Signature-Timestamp
    required
    string
    Unix time in milliseconds used in the signature. Must be within 5 minutes of Orbita's clock.
    Content-Type
    required
    string
    application/json, or multipart/form-data when the endpoint accepts a file.

    Body parameters

    fromCurrency
    required
    string
    Currency to debit. Lowercase currency code, e.g. ngn, usd, gbp.
    toCurrency
    required
    string
    Currency to credit. Lowercase currency code, e.g. ngn, usd, gbp.
    amount
    required
    number | string
    Amount to convert, in fromCurrency, in major units (e.g. 1600000 or "1600000.50").
    quoteCode
    optional
    string
    Code of an active quote from List quotes. Its currencies must match. Omit to convert at the current public rate.

    Behaviour

    Your business must have completed KYC verification.

    The response returns straight away with status processing. Poll Get a conversion until it is completed — the converted amount is then in your toCurrency balance. If a conversion fails, the debited amount is refunded.

    This endpoint has no idempotency key. If a request times out, check List conversions before retrying, or you may convert twice.

    Response

    data confirms the conversion was accepted. Every response is wrapped in the standard envelope.

    conversionId
    string (uuid)
    ID of the new conversion.
    status
    string
    processing when accepted.
    proposedCompletionTime
    string (datetime)
    When the conversion is expected to complete.

    Errors

    Errors specific to this endpoint:

    400
    Validation failed
    A field is missing or invalid. data.errors lists each problem.
    400
    You must be verified to swap currency
    Your business hasn't completed KYC verification.
    400
    No rate found for ngn to kes
    Orbita doesn't currently offer the pair.
    400
    Insufficient funds
    Your fromCurrency balance is lower than amount.
    400
    Quote not found
    quoteCode doesn't exist.
    400
    Quote has expired
    The quote is past its expiresAt.
    400
    Quote has already been used
    The quote was used by an earlier conversion.
    400
    Quote currencies do not match payload
    The quote is for a different pair than fromCurrency/toCurrency.

    Plus the errors every endpoint can return — authentication, signing, rate limiting and server errors. See Responses & errors.