Participant Service

Manages participants and participant addresses.

---

Endpoints

---

Create Participant

POST /participants

Create a new participant.

Request Body

Field	Type	Required	Description	Example
institutionName	string	Yes	Institution name. Must be non-empty.	"Acme Corp"
routerData	object	No	Optional router configuration data.	{"key": "value"}
authConsumerId	string	Yes	API key for the participant. Must be non-empty.	"test-api-key"
customers	array	Yes	List of customers associated with the participant. See CreateCustomerDto.	[ ... ]

Example Request:

{
  "institutionName": "Acme Corp",
  "routerData": { "key": "value", "settings": { "enabled": true } },
  "authConsumerId": "test-api-key",
  "customers": [
    {
      "externalId": "customer-external-id",
      "status": "active",
      "accounts": [
        {
          "customerId": "eac6de80-8a71-4dc3-abee-240214cea9d5",
          "type": "STABLECOINS",
          "status": "active",
          "name": "Main Account"
        }
      ]
    }
  ]
}

Success Response

Returns the created participant object.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "institutionName": "Acme Corp",
  "authConsumerId": "test-api-key",
  "omnibusAccountId": "omnibus-uuid",
  "feePayerAccountId": "fee-payer-uuid",
  "customers": [
    {
      "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
      "externalId": "customer-external-id",
      "status": "active",
      "accounts": [
        {
          "customerId": "eac6de80-8a71-4dc3-abee-240214cea9d5",
          "type": "STABLECOINS",
          "status": "active",
          "name": "Main Account"
        }
      ]
    }
  ],
  "createdAt": "2025-11-18T12:34:56.789Z",
  "updatedAt": "2025-11-18T12:34:56.789Z",
  "routerData": { "key": "value", "settings": { "enabled": true } }
}

Error Responses

• 400 Bad Request: Validation failed (missing or invalid fields)

---

Get Participant

GET /participants/:id

Retrieve details for a specific participant.

Path Parameters

Parameter	Type	Required	Description
id	uuid	Yes	Participant unique ID

Success Response

Returns the participant object (see above).

Error Responses

• 404 Not Found: Participant not found

---

List Participants

GET /participants

Retrieve a list of participants, with filtering and pagination.

Query Parameters

Parameter	Type	Description	Example
institutionName	string	Filter by institution name	"Acme"
address	string	Filter by blockchain address	"38xz..."
blockchain	string	Filter by blockchain	"solana"
routerData	string	Filter by router data	"someKey"
limit	number	Number of records to return (default: 10)	10
offset	number	Number of records to skip (default: 0)	0

Example Request:

/participants?institutionName=Acme&limit=10&offset=0

Success Response

Returns an array of participant objects.

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "institutionName": "Acme Corp",
    "authConsumerId": "test-api-key",
    "customers": [ ... ],
    "createdAt": "2025-11-18T12:34:56.789Z",
    "updatedAt": "2025-11-18T12:34:56.789Z",
    "routerData": { "key": "value" }
  }
  // ...more participants
]

---

Update Participant

PATCH /participants/:id

Update participant information.

Path Parameters

Parameter	Type	Required	Description
id	uuid	Yes	Participant unique ID

Request Body

Field	Type	Required	Description	Example
institutionName	string	No	Institution name.	"Acme Corp"
routerData	object	No	Router configuration data.	{"key": "value"}
authConsumerId	string	No	API key for the participant.	"test-api-key"
customers	array	No	List of customers associated with the participant. See CreateCustomerDto.	[ ... ]

Example Request:

{
  "institutionName": "Acme Corp",
  "routerData": { "key": "value" }
}

Success Response

Returns the updated participant object.

Error Responses

• 404 Not Found: Participant not found

---

Replace Participant

PUT /participants/:id

Replace participant information.

Path Parameters

Parameter	Type	Required	Description
id	uuid	Yes	Participant unique ID

Request Body

Field	Type	Required	Description	Example
institutionName	string	Yes	Institution name.	"Acme Corp"
routerData	object	Yes	Router configuration data.	{"key": "value"}
authConsumerId	string	Yes	API key for the participant.	"test-api-key"
customers	array	Yes	List of customers associated with the participant. See CreateCustomerDto.	[ ... ]

Example Request:

{
  "institutionName": "Acme Corp",
  "routerData": { "key": "value" },
  "authConsumerId": "test-api-key",
  "customers": [ ... ]
}

Success Response

Returns the replaced participant object.

Error Responses

• 404 Not Found: Participant not found

---

Delete Participant

DELETE /participants/:id

Delete a participant.

Path Parameters

Parameter	Type	Required	Description
id	uuid	Yes	Participant unique ID

Success Response

• 204 No Content: Participant deleted

Error Responses

• 404 Not Found: Participant not found

---

Error Format

All error responses follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Description of the error",
    "details": [
      {
        "field": "fieldName",
        "message": "Field-specific error message"
      }
    ]
  }
}

---

Field Descriptions

Field	Type	Description
id	uuid	Unique identifier for the participant
institutionName	string	Institution name
authConsumerId	string	API key for the participant
omnibusAccountId	string	Omnibus account ID (optional)
feePayerAccountId	string	Fee payer account ID (optional)
customers	array	List of customers associated with the participant
createdAt	string	ISO8601 timestamp of participant creation
updatedAt	string	ISO8601 timestamp of last update
deletedAt	string	ISO8601 timestamp of deletion (optional)
routerData	object	Router configuration data (optional)

---

For nested customer and account fields, see CreateCustomerDto and CreateAccountDto definitions.