Skip to content
Farcaster

Configure or update the tenant's settlement facilitator

PATCH
/v1/settlement/config
curl --request PATCH \
  --url https://example.com/v1/settlement/config \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "facilitator_url": "https://example.com", "facilitator_credential_ref": "example" }'

Both fields are optional on the wire; an absent field leaves its current value unchanged. The first configure call for a tenant must supply both (spec 0006 Decision 1). facilitator_credential_ref must resolve to a credential owned by the same tenant.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Both fields optional; an absent field leaves the current value unchanged. The first configure call for a tenant must supply both.

object
facilitator_url

Must be https with a host; loopback/private/link-local hosts and localhost are rejected.

string format: uri
facilitator_credential_ref

Must resolve to a credential owned by the same tenant.

string
Examplegenerated
{
  "facilitator_url": "https://example.com",
  "facilitator_credential_ref": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

The updated settlement configuration.

Media typeapplication/json
object
facilitator_url
required
string format: uri
facilitator_credential_ref
required
string
created_at
required
string format: date-time
updated_at
required
string format: date-time
Examplegenerated
{
  "facilitator_url": "https://example.com",
  "facilitator_credential_ref": "example",
  "created_at": "2026-04-15T12:00:00Z",
  "updated_at": "2026-04-15T12:00:00Z"
}

400

Section titled “400”

Empty field value, an invalid facilitator_url, an unresolvable facilitator_credential_ref, or an incomplete first configure.

Media typeapplication/json

The uniform error body for all 4xx responses that carry one.

object
error
required

A coarse, caller-safe message. Never contains internal state (invariant

string
Examplegenerated
{
  "error": "example"
}

401

Section titled “401”

Missing or invalid bearer token, or the token’s tenant/user claims are absent. No body.

500

Section titled “500”

An unexpected server-side error. No body (internal detail is never returned to callers, invariant