# Relayer Accounts

## Returns the list of Relayer Accounts of the active user.

> Returns the list of Relayer Accounts owned by the currently authenticated user. Supports pagination and text search by account name or Hedera account ID.

```json
{"openapi":"3.0.0","info":{"title":"Guardian","version":"3.6.0-rc"},"servers":[{"url":"/api/v1","description":"version 1.0"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RelayerAccountDTO":{"type":"object","properties":{"id":{"type":"string","description":"Internal database identifier"},"name":{"type":"string","description":"Human-readable name of the relayer account"},"username":{"type":"string","description":"Username of the relayer account owner"},"owner":{"type":"string","description":"DID of the relayer account owner"},"parent":{"type":"string","description":"DID of the parent Standard Registry (for child users)","nullable":true},"account":{"type":"string","description":"Hedera account ID of the relayer"},"createDate":{"type":"string","description":"Creation date in ISO 8601 format"},"updateDate":{"type":"string","description":"Last update date in ISO 8601 format"}},"required":["id"]},"UnauthorizedErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"}},"required":["statusCode","message"]},"ForbiddenErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"},"error":{"type":"string"}},"required":["statusCode","message"]},"InternalServerErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"}},"required":["statusCode","message"]}}},"paths":{"/relayer-accounts":{"get":{"description":"Returns the list of Relayer Accounts owned by the currently authenticated user. Supports pagination and text search by account name or Hedera account ID.","operationId":"RelayerAccountsApi_getRelayerAccounts","parameters":[{"name":"pageIndex","required":false,"in":"query","description":"The number of pages to skip before starting to collect the result set","schema":{"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"The numbers of items to return","schema":{"type":"number"}},{"name":"search","required":false,"in":"query","description":"Filter by account name or Hedera account ID (case-insensitive, partial match). Leave empty to return all.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful operation. Returns relayer accounts array and total count in X-Total-Count header.","headers":{"X-Total-Count":{"schema":{"type":"integer"},"description":"Total items in the collection."}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RelayerAccountDTO"}}}}},"401":{"description":"Unauthorized request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedErrorDTO"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Returns the list of Relayer Accounts of the active user.","tags":["relayer-accounts"]}}}}
```

## Adds a new Relayer Account for the active user.

> Creates a new Relayer Account by associating an existing Hedera account (account ID + private key) with the current user. The key is stored securely in the wallet.

```json
{"openapi":"3.0.0","info":{"title":"Guardian","version":"3.6.0-rc"},"servers":[{"url":"/api/v1","description":"version 1.0"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"NewRelayerAccountDTO":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name for the new relayer account"},"account":{"type":"string","description":"Hedera account ID to use as relayer"},"key":{"type":"string","description":"Private key for the Hedera account (stored securely in wallet)"}}},"RelayerAccountDTO":{"type":"object","properties":{"id":{"type":"string","description":"Internal database identifier"},"name":{"type":"string","description":"Human-readable name of the relayer account"},"username":{"type":"string","description":"Username of the relayer account owner"},"owner":{"type":"string","description":"DID of the relayer account owner"},"parent":{"type":"string","description":"DID of the parent Standard Registry (for child users)","nullable":true},"account":{"type":"string","description":"Hedera account ID of the relayer"},"createDate":{"type":"string","description":"Creation date in ISO 8601 format"},"updateDate":{"type":"string","description":"Last update date in ISO 8601 format"}},"required":["id"]},"UnauthorizedErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"}},"required":["statusCode","message"]},"ForbiddenErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"},"error":{"type":"string"}},"required":["statusCode","message"]},"UnprocessableEntityErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string"}},"required":["statusCode","message"]},"InternalServerErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"}},"required":["statusCode","message"]}}},"paths":{"/relayer-accounts":{"post":{"description":"Creates a new Relayer Account by associating an existing Hedera account (account ID + private key) with the current user. The key is stored securely in the wallet.","operationId":"RelayerAccountsApi_createRelayerAccount","parameters":[],"requestBody":{"required":true,"description":"New Relayer Account configuration. Requires a valid Hedera account ID and its private key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewRelayerAccountDTO"}}}},"responses":{"200":{"description":"Successful operation. Returns the created relayer account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelayerAccountDTO"}}}},"401":{"description":"Unauthorized request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedErrorDTO"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"422":{"description":"Unprocessable entity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityErrorDTO"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Adds a new Relayer Account for the active user.","tags":["relayer-accounts"]}}}}
```

## Returns current (default) Relayer Account of the active user.

> Returns the default Hedera account of the active user, which is used as the relayer when no specific relayer account is selected.

```json
{"openapi":"3.0.0","info":{"title":"Guardian","version":"3.6.0-rc"},"servers":[{"url":"/api/v1","description":"version 1.0"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"UnauthorizedErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"}},"required":["statusCode","message"]},"ForbiddenErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"},"error":{"type":"string"}},"required":["statusCode","message"]},"InternalServerErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"}},"required":["statusCode","message"]}}},"paths":{"/relayer-accounts/current":{"get":{"description":"Returns the default Hedera account of the active user, which is used as the relayer when no specific relayer account is selected.","operationId":"RelayerAccountsApi_getCurrentRelayerAccount","parameters":[],"responses":{"200":{"description":"Successful operation. Returns the default account info (name is always \"Default\").","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Account name (always \"Default\")"},"owner":{"type":"string","description":"Owner DID"},"account":{"type":"string","description":"Hedera account ID"}}}}}},"401":{"description":"Unauthorized request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedErrorDTO"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Returns current (default) Relayer Account of the active user.","tags":["relayer-accounts"]}}}}
```

## Returns the list of Relayer Accounts available for use in the Policy by the active user.

> Returns all Relayer Accounts owned by the current user. Unlike GET /, this endpoint returns all accounts without pagination.

```json
{"openapi":"3.0.0","info":{"title":"Guardian","version":"3.6.0-rc"},"servers":[{"url":"/api/v1","description":"version 1.0"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RelayerAccountDTO":{"type":"object","properties":{"id":{"type":"string","description":"Internal database identifier"},"name":{"type":"string","description":"Human-readable name of the relayer account"},"username":{"type":"string","description":"Username of the relayer account owner"},"owner":{"type":"string","description":"DID of the relayer account owner"},"parent":{"type":"string","description":"DID of the parent Standard Registry (for child users)","nullable":true},"account":{"type":"string","description":"Hedera account ID of the relayer"},"createDate":{"type":"string","description":"Creation date in ISO 8601 format"},"updateDate":{"type":"string","description":"Last update date in ISO 8601 format"}},"required":["id"]},"UnauthorizedErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"}},"required":["statusCode","message"]},"ForbiddenErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"},"error":{"type":"string"}},"required":["statusCode","message"]},"InternalServerErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"}},"required":["statusCode","message"]}}},"paths":{"/relayer-accounts/all":{"get":{"description":"Returns all Relayer Accounts owned by the current user. Unlike GET /, this endpoint returns all accounts without pagination.","operationId":"RelayerAccountsApi_getRelayerAccountsAll","parameters":[],"responses":{"200":{"description":"Successful operation.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RelayerAccountDTO"}}}}},"401":{"description":"Unauthorized request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedErrorDTO"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Returns the list of Relayer Accounts available for use in the Policy by the active user.","tags":["relayer-accounts"]}}}}
```

## Returns current HBAR balance of the specified Relayer Account.

> Queries the Hedera network for the current HBAR balance of the specified account. The account must belong to the current user or be a relayer account owned by them.

```json
{"openapi":"3.0.0","info":{"title":"Guardian","version":"3.6.0-rc"},"servers":[{"url":"/api/v1","description":"version 1.0"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"UnauthorizedErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"}},"required":["statusCode","message"]},"ForbiddenErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"},"error":{"type":"string"}},"required":["statusCode","message"]},"InternalServerErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"}},"required":["statusCode","message"]}}},"paths":{"/relayer-accounts/{account}/balance":{"get":{"description":"Queries the Hedera network for the current HBAR balance of the specified account. The account must belong to the current user or be a relayer account owned by them.","operationId":"RelayerAccountsApi_getRelayerAccountBalance","parameters":[{"name":"account","required":true,"in":"path","description":"Hedera account ID of the relayer account","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful operation. Returns the HBAR balance as a string (e.g. \"999.34 tℏ\").","content":{"application/json":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedErrorDTO"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Returns current HBAR balance of the specified Relayer Account.","tags":["relayer-accounts"]}}}}
```

## Generate a new Relayer Account.

> Generates a new Hedera account on the network and registers it as a Relayer Account for the current user. The account is created and funded automatically.

```json
{"openapi":"3.0.0","info":{"title":"Guardian","version":"3.6.0-rc"},"servers":[{"url":"/api/v1","description":"version 1.0"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"UnauthorizedErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"}},"required":["statusCode","message"]},"ForbiddenErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"},"error":{"type":"string"}},"required":["statusCode","message"]},"UnprocessableEntityErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string"}},"required":["statusCode","message"]},"InternalServerErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"}},"required":["statusCode","message"]}}},"paths":{"/relayer-accounts/generate":{"post":{"description":"Generates a new Hedera account on the network and registers it as a Relayer Account for the current user. The account is created and funded automatically.","operationId":"RelayerAccountsApi_generateRelayerAccount","parameters":[],"responses":{"200":{"description":"Successful operation. Returns the generated Hedera account ID and private key. Store the key securely — it is only returned once.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Generated Hedera account ID"},"key":{"type":"string","description":"Private key for the generated account (hex-encoded DER)"}}}}}},"401":{"description":"Unauthorized request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedErrorDTO"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"422":{"description":"Unprocessable entity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityErrorDTO"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Generate a new Relayer Account.","tags":["relayer-accounts"]}}}}
```

## Return the list of Relayer Accounts for the user.

> If the active user is a Standard Registry, returns the list of all users (and their relayer accounts) under this SR. Each user appears once per relayer account plus once for the default account (with null relayer fields).

```json
{"openapi":"3.0.0","info":{"title":"Guardian","version":"3.6.0-rc"},"servers":[{"url":"/api/v1","description":"version 1.0"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"UnauthorizedErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"}},"required":["statusCode","message"]},"ForbiddenErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"},"error":{"type":"string"}},"required":["statusCode","message"]},"InternalServerErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"}},"required":["statusCode","message"]}}},"paths":{"/relayer-accounts/accounts":{"get":{"description":"If the active user is a Standard Registry, returns the list of all users (and their relayer accounts) under this SR. Each user appears once per relayer account plus once for the default account (with null relayer fields).","operationId":"RelayerAccountsApi_getUserRelayerAccounts","parameters":[{"name":"pageIndex","required":false,"in":"query","description":"The number of pages to skip before starting to collect the result set","schema":{"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"The numbers of items to return","schema":{"type":"number"}},{"name":"search","required":false,"in":"query","description":"Filter by username, Hedera account ID, relayer account ID or name (case-insensitive, partial match)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful operation. Returns users with their relayer accounts and total count in X-Total-Count header.","headers":{"X-Total-Count":{"schema":{"type":"integer"},"description":"Total items in the collection."}},"content":{"application/json":{}}},"401":{"description":"Unauthorized request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedErrorDTO"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Return the list of Relayer Accounts for the user.","tags":["relayer-accounts"]}}}}
```

## Return the list of VC documents associated with the selected Relayer Account.

> Returns paginated VC documents that were created using the specified relayer account. Each document is enriched with policyName, policyVersion, and schemaName.

```json
{"openapi":"3.0.0","info":{"title":"Guardian","version":"3.6.0-rc"},"servers":[{"url":"/api/v1","description":"version 1.0"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"VcDocumentDTO":{"type":"object","properties":{"id":{"type":"string"},"policyId":{"type":"string"},"hash":{"type":"string"},"signature":{"type":"number"},"status":{"type":"string","enum":["NEW","ISSUE","REVOKE","SUSPEND","RESUME","FAILED"]},"tag":{"type":"string"},"type":{"type":"string"},"createDate":{"type":"string"},"updateDate":{"type":"string"},"owner":{"type":"string"},"hederaStatus":{"type":"string"},"option":{"type":"object","additionalProperties":true},"topicId":{"type":"string"},"messageId":{"type":"string"},"document":{"$ref":"#/components/schemas/VcDTO"}}},"VcDTO":{"type":"object","properties":{"id":{"type":"string","nullable":true},"@context":{"type":"array","items":{"type":"string"}},"type":{"type":"array","items":{"type":"string"}},"credentialSubject":{"additionalProperties":true,"type":"array","items":{"type":"object"}},"issuer":{"oneOf":[{"type":"string"},{"type":"object","additionalProperties":true}]},"issuanceDate":{"type":"string"},"proof":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/ProofDTO"}]}},"required":["id","@context","type","credentialSubject","issuer","issuanceDate","proof"]},"ProofDTO":{"type":"object","properties":{"type":{"type":"string"},"created":{"type":"string"},"verificationMethod":{"type":"string"},"proofPurpose":{"type":"string"},"jws":{"type":"string"}},"required":["type","created","verificationMethod","proofPurpose","jws"]},"UnauthorizedErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"}},"required":["statusCode","message"]},"ForbiddenErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"},"error":{"type":"string"}},"required":["statusCode","message"]},"InternalServerErrorDTO":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"}},"required":["statusCode","message"]}}},"paths":{"/relayer-accounts/{relayerAccountId}/relationships":{"get":{"description":"Returns paginated VC documents that were created using the specified relayer account. Each document is enriched with policyName, policyVersion, and schemaName.","operationId":"RelayerAccountsApi_getRelayerAccountRelationships","parameters":[{"name":"relayerAccountId","required":true,"in":"path","description":"Hedera account ID of the Relayer Account (not the database ID)","schema":{"type":"string"}},{"name":"pageIndex","required":false,"in":"query","description":"The number of pages to skip before starting to collect the result set","schema":{"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"The numbers of items to return","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful operation. Returns VC documents and total count in X-Total-Count header.","headers":{"X-Total-Count":{"schema":{"type":"integer"},"description":"Total items in the collection."}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/VcDocumentDTO"}}}}},"401":{"description":"Unauthorized request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedErrorDTO"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Return the list of VC documents associated with the selected Relayer Account.","tags":["relayer-accounts"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.guardian.hedera.com/api-reference/relayer-accounts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.