POST & PATCH /v1/keys

Two endpoints on the same resource: POST creates a key, PATCH updates the fee, payout addresses, and webhook on a key you already have. See Get an API key for the hosted signup form, Pricing for how the fee you set here turns into a payout, and Settlement Webhooks for what the webhook actually sends.

Create a key: POST /v1/keys

string

required

Where you receive your key and any partnership follow-up.

string

required

string

required

A valid URL.

string

required

string

required

string

Optional.

string

Optional, one line on what you’re building.

string

Optional.

string[]

Optional.

string[]

Optional.

integer

Your swap fee in basis points, 0 to 100 (1%). Omit or send 0 to start at 0%; you can raise it later with PATCH. See Pricing for what you actually receive of whatever you set.

No API key required to call this endpoint; it’s how you get one. Rate-limited to 5 signups/min per IP.

curl -s -X POST https://app.ravn.exchange/api/v1/keys \
  -H 'content-type: application/json' -d '{
    "email": "you@project.xyz",
    "projectName": "Your Project",
    "website": "https://project.xyz",
    "telegram": "@yourproject",
    "twitter": "@yourproject",
    "feeBps": 20
  }'

string

Pass as the x-api-key header on every other v1 request.

string

integer

The fee now active on this key, 0 if omitted above.

{ "data": { "apiKey": "rvn_live_...", "partnerId": "...", "feeBps": 20 } }

Update a key: PATCH /v1/keys

Change the calling key’s own fee, register where its share of collected fees gets paid out, and/or register a settlement webhook. Authenticated by the same x-api-key header as every other endpoint; the key itself is your proof of ownership. At least one of feeBps, payoutAddresses, or webhookUrl is required.

integer

0 to 100 (1%). Self-serve keys only (see the note below).

object

One or more of evm, solana, thorchain (must match thor1…, 38 lowercase alphanumeric characters after the prefix). Registers where that ecosystem’s earned balance is sent: in-kind, in the token each fee landed in, monthly on the 1st at 03:30 UTC, only for swaps that reached settled, and only once a token balance is worth at least $5. See Pricing for the rules and what happens if a balance accrues with no address on file.

string

Must be https://. Registers where RAVN posts a notification when a swap made with this key settles, gets refunded, or fails. Self-serve keys only, same restriction as feeBps. See Settlement Webhooks for the payload shape and signature verification.

curl -s -X PATCH https://app.ravn.exchange/api/v1/keys \
  -H 'x-api-key: rvn_live_your_key_here' \
  -H 'content-type: application/json' -d '{
    "feeBps": 25,
    "payoutAddresses": { "evm": "0xYourPayoutAddress" },
    "webhookUrl": "https://your-service.example/ravn-webhook"
  }'

{
  "data": {
    "feeBps": 25,
    "payoutAddresses": { "evm": "0xYourPayoutAddress" },
    "webhookUrl": "https://your-service.example/ravn-webhook",
    "webhookSecret": "a1b2c3..."
  }
}

string

Only present when this call set webhookUrl, and only ever shown once, from this exact call. There’s no separate endpoint to retrieve it again, save it immediately. Re-registering a different webhookUrl later keeps the same secret rather than issuing a new one.

Enterprise keys set feeBps a different way, and don’t support webhooks yet. Enterprise keys aren’t self-serve rows, so a feeBps or webhookUrl update here returns 404 NOT_FOUND for one. Your fee on an enterprise key is set directly by RAVN as part of your arrangement (see Authentication). payoutAddresses still works on an enterprise key; feeBps and webhookUrl are restricted.

Returns 401 UNAUTHORIZED with no x-api-key header (there’s no anonymous key to update), 404 NOT_FOUND on a feeBps or webhookUrl update for a non-self-serve key, and 400 INVALID_REQUEST if no field is present or a value fails validation (an out-of-range feeBps, a malformed thorchain address, or a webhookUrl that isn’t https://).

​Create a key: POST /v1/keys

​Update a key: PATCH /v1/keys

Create a key: POST /v1/keys

Update a key: PATCH /v1/keys