> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravn.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# POST & PATCH /v1/keys

> Create a self-serve API key, then set your own swap fee, payout addresses, and settlement webhook.

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](/tools/get-api-key) for
the hosted signup form, [Pricing](/pricing) for how the fee you set here turns into a payout,
and [Settlement Webhooks](/webhooks) for what the webhook actually sends.

## Create a key: POST /v1/keys

<ParamField body="email" type="string" required>Where you receive your key and any partnership follow-up.</ParamField>

<ParamField body="projectName" type="string" required />

<ParamField body="website" type="string" required>A valid URL.</ParamField>

<ParamField body="telegram" type="string" required />

<ParamField body="twitter" type="string" required />

<ParamField body="discord" type="string">Optional.</ParamField>
<ParamField body="blurb" type="string">Optional, one line on what you're building.</ParamField>
<ParamField body="category" type="string">Optional.</ParamField>
<ParamField body="chains" type="string[]">Optional.</ParamField>
<ParamField body="apisPlanned" type="string[]">Optional.</ParamField>

<ParamField body="feeBps" type="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](/pricing#setting-your-own-fee) for what you actually receive of
  whatever you set.
</ParamField>

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

```bash theme={null}
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
  }'
```

<ResponseField name="apiKey" type="string">Pass as the `x-api-key` header on every other v1 request.</ResponseField>

<ResponseField name="partnerId" type="string" />

<ResponseField name="feeBps" type="integer">The fee now active on this key, `0` if omitted above.</ResponseField>

```json theme={null}
{ "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.

<ParamField body="feeBps" type="integer">0 to 100 (1%). Self-serve keys only (see the note below).</ParamField>

<ParamField body="payoutAddresses" type="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](/pricing#getting-paid) for the rules and what happens if a balance accrues with no
  address on file.
</ParamField>

<ParamField body="webhookUrl" type="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](/webhooks) for the payload shape and signature verification.
</ParamField>

```bash theme={null}
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"
  }'
```

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

<ResponseField name="webhookSecret" type="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.
</ResponseField>

<Note>
  **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](/authentication#enterprise-partnerships)). `payoutAddresses` still works on an
  enterprise key; `feeBps` and `webhookUrl` are restricted.
</Note>

<Warning>
  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://`).
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.