ravnexchange (Python) - RAVN

pip install ravnexchange

from ravnexchange import RavnClient, RavnApiError

client = RavnClient(api_key="rvn_live_…")  # optional: omit for the anonymous tier

try:
    quote = client.get_quote({
        "inputChainId": 1,
        "outputChainId": -2,
        "inputToken": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        "outputToken": "So11111111111111111111111111111111111111112",
        "inputAmount": "1000000000000000000",
        "userAddress": "0x1111111111111111111111111111111111111111",
        "destinationAddress": "YourSo1anaWa11etAddressGoesHere311111111111",
    })
    execution = client.execute({"quoteToken": quote["quoteToken"]})
    # Branch on execution["executionType"]: see Execution types.
except RavnApiError as e:
    print(e.code, e.details, str(e))

Methods are snake_case, but request fields keep the API’s camelCase keys. Each method returns the response’s data and raises RavnApiError (code, details, meta; the message is str(e)) on failure. The client signs nothing: handle each execution as in Execution types.

Method	Endpoint
`get_quote(params)`	`POST /quote`
`execute(params)`	`POST /execute`
`submit_signature(params)`	`POST /submit-signature`
`submit_transaction(params)`	`POST /submit-transaction`
`get_status(quote_token, ref, tx_hash=None)`	`POST /status`
`get_tokens(chain_id)`, `get_chains()`	`GET /tokens`, `GET /chains`
`recover(params, user_address)`	One step of `POST /recover`, checked

execute

For a Hinkal quote sent with authorizeSteps: True, execute first answers AUTHORIZE twice. Check each step with check_authorize, sign it with the paying wallet, and call execute again until the TRANSACTION comes back. Check that with check_hinkal_deposit before sending anything.

import time
from eth_account import Account
from eth_account.messages import encode_defunct
from ravnexchange import check_authorize, check_hinkal_deposit

account = Account.from_key(private_key)  # the paying wallet: the quote's userAddress
while execution["executionType"] == "AUTHORIZE":
    check_authorize(execution, params)  # params: what you passed to get_quote
    sign = execution["sign"]
    if sign["method"] == "personal_sign":
        signature = account.sign_message(encode_defunct(text=sign["message"])).signature
    else:
        order_received = time.time()  # send the deposit within 10 minutes of this
        signature = account.sign_typed_data(full_message=sign["typedData"]).signature
    execution = client.execute({
        "quoteToken": quote["quoteToken"],
        "authorization": execution["authorization"],
        "signature": signature,
    })
check_hinkal_deposit(execution, params)

Both raise UnsafeExecutionError when a step isn’t what your user asked for. This client checks Hinkal’s answers only, not other venues’.

recover_stuck_funds

Gets a failed Hinkal swap’s funds back to the paying wallet, checking every step:

from ravnexchange import recover_stuck_funds

recovered = recover_stuck_funds(
    client,
    status_ref=execution["statusRef"],
    user_address=account.address,  # the paying wallet, from your own wallet
    sign_message=lambda message: account.sign_message(encode_defunct(text=message)).signature,
    sign_typed_data=lambda typed: account.sign_typed_data(full_message=typed).signature,
)

Building an AI agent? The MCP server covers the same calls with no code.