ravnexchange (Python)

A zero-dependency Python client with the same scope as @ravnexchange/sdk: quote, execute, submit-signature, status, tokens, and chains, snake_cased. This is for a plain, non-agent Python backend that wants a typed wrapper instead of hand-rolling POST/GET calls against the JSON API.

Building an AI agent instead of a backend service? Use RAVN’s MCP server rather than this package, it’s free, already speaks the agent’s tool-calling protocol, and covers this same surface plus more.

Setup

pip install ravnexchange

from ravnexchange import RavnClient

client = RavnClient(api_key="rvn_live_your_key_here")  # omit for the anonymous tier

str

Self-serve or enterprise key. Omit for the anonymous tier: it works immediately, at a lower rate limit. See Authentication.

str

Default https://app.ravn.exchange/api/v1.

callable

Swap in your own opener for tests or an unusual runtime. Defaults to urllib.request.urlopen. Built on the stdlib urllib.request, not requests, so installing this package adds nothing to your dependency tree.

Full example

from ravnexchange import RavnClient, RavnApiError

client = RavnClient(api_key="rvn_live_your_key_here")

try:
    quote = client.get_quote({
        "inputChainId": 1,
        "outputChainId": 8453,
        "inputToken": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        "outputToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "inputAmount": "1000000000000000000",
        "userAddress": "0xYourAddress",
        "destinationAddress": "0xYourAddress",
    })
except RavnApiError as e:
    print(e.code, str(e))
else:
    execution = client.execute({"quoteToken": quote["quoteToken"]})
    # branch on execution["executionType"]: TRANSACTION / SIGNATURE / DEPOSIT

Request fields are still the camelCase keys the API expects (inputChainId, not input_chain_id), the client is a typed wrapper, not a schema translator. Only the method names themselves are snake_case.

Methods

Every method returns the unwrapped data from the response envelope, and raises RavnApiError on anything else. Field meanings match the API Reference pages linked from each method.

get_quote

quote = client.get_quote({
    "inputChainId": 1,
    "outputChainId": -2,
    "inputToken": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
    "outputToken": "So11111111111111111111111111111111111111112",
    "inputAmount": "1000000000000000000",
    "userAddress": "0xYourUser",
    "destinationAddress": "SoYourUser",
})

Wraps POST /quote. Omitting destinationAddress/refundAddress returns a preview-only quote, so check quote["executable"] before calling execute. Supports sandbox: True the same as the raw API, see Sandbox Mode, and confidential: True for a private swap (0.1.3 or later).

execute

execution = client.execute({"quoteToken": quote["quoteToken"]})

if execution["executionType"] == "DEPOSIT":
    ...
elif execution["executionType"] == "SIGNATURE":
    ...
elif execution["executionType"] == "TRANSACTION":
    ...

Wraps POST /execute. This client doesn’t sign or send anything for you, branch on executionType exactly as in the Quickstart.

submit_signature

result = client.submit_signature({
    "quoteToken": execution["quoteToken"],
    "signature": sig,
})

Wraps POST /submit-signature. Only for SIGNATURE-type executions. Pass execution["quoteToken"], not the quote’s own. Returns {"statusRef": ...} to poll get_status with.

get_status

status = client.get_status(execution["quoteToken"], status_ref)

Wraps /status. Pass execution["quoteToken"], not the quote’s own: a two-hop RAVN route is rebound at execute. ref is the statusRef from execute (for DEPOSIT, and TRANSACTION when present), from submit_signature (for SIGNATURE), or otherwise the transaction hash you broadcast (for TRANSACTION). Once terminal, a venue that reports it adds deliveredAmount and txHash to the result. Poll every swap to a terminal state: that is what settles it for fee payout, see Settlement.

get_tokens

tokens = client.get_tokens(1)  # chainId

Wraps GET /tokens for the given chain.

get_chains

chains = client.get_chains()

Wraps GET /chains. Static, safe to cache client-side.

Errors

Every non-2xx response, or a 2xx body that still carries an error field, raises RavnApiError:

from ravnexchange import RavnApiError

try:
    client.execute({"quoteToken": quote_token})
except RavnApiError as e:
    print(e.code, e.details, str(e))

str

The stable, machine-readable code. See Errors for the full table.

Any

Present on some codes, for example the failed fields on INVALID_REQUEST.

dict

requestId and version, when the API returned an envelope at all.

The human-readable message isn’t a separate .message attribute (Python’s base Exception doesn’t give you one for free); read it with str(e) instead, same value the TS client’s err.message carries.

​Setup

​Full example

​Methods

​get_quote

​execute

​submit_signature

​get_status

​get_tokens

​get_chains

​Errors

Setup

Full example

Methods

get_quote

execute

submit_signature

get_status

get_tokens

get_chains

Errors