Developer docs

Point your mediator URL here — one line.

Any DIDComm v2 agent can mediate through the relay — CoordinateMediation 2.0, Pickup Protocol 3.0, and forward routing, all standards-track. The management API below is read/manage; docs are free, no login required to read.

Get an API key

Quickstart

Point the mediator URL at the relay.

There is no separate SDK to install for the base flow — set your agent's mediator URL and run mediate-request. The relay grants mediation, hands back a keylist, and starts forwarding.

Mediator endpoint

1# any DIDComm v2 agent — point its mediator URL here:
2MEDIATOR_URL=https://relay.solidus.network/didcomm

Testnet · pre-launch — framework adapters below are planned and ship with launch.

Adapters

Works with the agents you already run.

Framework adapters are planned and ship with launch — they are not yet published to npm. The raw DIDComm v2 endpoint works today for any conformant agent.

Credo-TS

1// @solidus/credo-relay-adapter — planned, ships with launch
2import { Agent } from '@credo-ts/core'
3import { MediationRecipientModule } from '@credo-ts/didcomm'
4
5const agent = new Agent({
6  modules: {
7    mediationRecipient: new MediationRecipientModule({
8      mediatorInvitationUrl: 'https://relay.solidus.network/invite',
9    }),
10  },
11})

API reference

The management API.

Management API — read/manage; docs free, no login. Endpoints below cover mediations, keylists, queue status, and credential-gate policies, plus the on-chain resolution trace no other mediator publishes.

Mediations

GET

/v1/mediations

List all mediations, filterable by state and credential-gate.

GET

/v1/mediations/:id

Fetch a single mediation — state, gate result, keylist size, queue depth.

Sample response

{
  "id": "med_a7f2c9",
  "recipient_did": "did:solidus:z6MkjWn4qYdSx2vTbCpF7kMuGe5hZa9rLoDiB3yXf8EwVsQ6",
  "state": "granted",
  "gate": { "policy": "KYC-verified recipients", "state": "pass" },
  "keylist_size": 3,
  "queued": 812,
  "delivered_24h": 96,
  "granted_ago": "2d",
  "protocols": ["coordinate-mediation/2.0","messagepickup/3.0"]
}

GET

/v1/mediations/:id/keylist

The recipient's routing keys and messages-routed count per key.

POST

/v1/mediations/:id/grant

Operator override — grant a pending mediation (on top of the auto gate decision).

POST

/v1/mediations/:id/deny

Operator override — deny a mediation with a reason.

POST

/v1/mediations/:id/revoke

Terminate a mediation and tear down its keylist.

DELETE

/v1/mediations/:id/keylist/:key

Remove a single routing key from a mediation keylist.

Queue & messages

GET

/v1/queue/status

Queue depth, oldest-queued age, and by-state counts.

GET

/v1/messages

List queued/delivered envelopes (metadata only — never ciphertext), filter by state/protocol/recipient.

GET

/v1/delivery-log

Operator event feed — scoped by recipient or mediation. Metadata only.

Policies & gating

GET

/v1/policies

List credential-gate policies — required VC type, issuer, disclosure, applies-to.

POST

/v1/policies

Create a credential-gate policy.

PATCH

/v1/policies/:id

Enable or disable a policy.

POST

/v1/policies/test

Run a credential against the gate — the SAME server-side check the live mediate-grant/delivery path uses.

PUT

/v1/policies/rate-limit

Set the per-DID rate limit (per-minute + burst).

PUT

/v1/policies/retention

Set message retention (days + purge-on-ack).

Keys & webhooks

GET

/v1/api-keys

List operator API keys (never the raw value).

POST

/v1/api-keys

Issue an API key — the raw slk_ value is returned exactly once.

DELETE

/v1/api-keys/:id

Revoke an API key.

GET

/v1/webhooks

List webhook endpoints + last delivery status.

PUT

/v1/webhooks

Subscribe a webhook endpoint to the 7 canonical events (HMAC-signed, SSRF-safe).

Routing resolution

GET

/v1/resolutions/:did

did:solidus routing-key and endpoint resolution trace — on-chain vs. cached, block-cited. No other mediator exposes this.

Sample response

{
  "did": "did:solidus:z6MkjWn4qYdSx2vTbCpF7kMuGe5hZa9rLoDiB3yXf8EwVsQ6",
  "routing_key": "z6LSfj9q…QtU0S1",
  "endpoint": "https://relay.solidus.network/didcomm",
  "source": "on-chain",
  "block": 4827391,
  "resolved_ago": "4m"
}

POST

/v1/resolutions/:did/re-resolve

Force a fresh on-chain resolution, bypassing the cache.

Webhooks

Events you can subscribe to.

Configure a webhook endpoint and subscribe to any of these from the operator console once you have an API key.

Event	When it fires
`mediation.granted`	A mediate-request is granted and the recipient's keylist is created.
`mediation.denied`	A mediate-request is denied — often a credential-gate block.
`message.queued`	A forwarded envelope is held for a recipient who is offline.
`message.delivered`	A queued message is picked up or delivered over a live connection.
`delivery.failed`	A delivery attempt to a live connection fails and will retry.
`gate.blocked`	A credential-gate policy rejects mediation or delivery.
`resolution.failed`	An on-chain did:solidus resolution fails and the mediator falls back to a cached endpoint.

Get an API key and point a mediator URL.

Free to start — 1 mediator DID, 1,000 messages a day, no sales call.

Get an API key