API docs by Redocly

Forja Issuance Platform API (0.4.0)

Download OpenAPI specification:

Implemented non-custodial ERC-20 issuance API for sandbox integration.

Forja never holds private keys and never signs. Integrators authenticate with HMAC, request an issuance, receive an unsigned ERC-20 mint transaction, sign it in their own infrastructure, then report either a txHash or a rawSignedTransaction for Forja to relay and watch. This specification intentionally documents only the routes implemented in the current API.

System

Health check

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

Fetch this OpenAPI document

Responses

Integrator Auth

Verify HMAC credentials

Use this endpoint before starting integration. A successful response returns the issuer id, environment, and scopes attached to the API key.

Authorizations:
HmacAuth

Responses

Response samples

Content type
application/json
{
  • "clientId": "string",
  • "issuerId": "string",
  • "scopes": [
    ],
  • "environment": "sandbox"
}

Tokens

List registered tokens

Authorizations:
HmacAuth
query Parameters
status
string
Enum: "active" "paused" "disabled"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get a registered token

Authorizations:
HmacAuth
path Parameters
tokenId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "issuerId": "string",
  • "symbol": "string",
  • "name": "string",
  • "decimals": 0,
  • "network": "polygon-amoy",
  • "contractAddress": "string",
  • "implementationAddress": "string",
  • "standard": "ERC20",
  • "status": "active",
  • "governanceMode": "eoa",
  • "governance": {
    },
  • "mintAuthority": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Issuances

Create an unsigned ERC-20 mint issuance

Creates an issuance in unsigned state and returns the full transaction to sign. HMAC clients must provide an Idempotency-Key header.

Authorizations:
HmacAuth
path Parameters
tokenId
required
string
header Parameters
Idempotency-Key
required
string
Request Body schema: application/json
required
amount
required
string^\d+(\.\d+)?$
destinationAddress
required
string^0x[a-fA-F0-9]{40}$
reference
string
object

Responses

Request samples

Content type
application/json
{
  • "amount": "1000.00",
  • "destinationAddress": "0x1111111111111111111111111111111111111111",
  • "reference": "sandbox-test-001",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tokenId": "string",
  • "issuerId": "string",
  • "amount": "string",
  • "destinationAddress": "string",
  • "reference": "string",
  • "metadata": { },
  • "status": "unsigned",
  • "unsignedTransaction": {
    },
  • "txHash": "string",
  • "rawSignedTransaction": "string",
  • "preflight": { },
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

List issuances

Authorizations:
HmacAuth
query Parameters
status
string (OperationStatus)
Enum: "unsigned" "submitted" "confirmed" "failed" "expired"
tokenId
string
limit
integer [ 1 .. 200 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get issuance status

Authorizations:
HmacAuth
path Parameters
issuanceId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tokenId": "string",
  • "issuerId": "string",
  • "amount": "string",
  • "destinationAddress": "string",
  • "reference": "string",
  • "metadata": { },
  • "status": "unsigned",
  • "unsignedTransaction": {
    },
  • "txHash": "string",
  • "rawSignedTransaction": "string",
  • "preflight": { },
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Report signed issuance transaction

Provide exactly one of txHash or rawSignedTransaction. If rawSignedTransaction is provided, Forja broadcasts it through the configured network RPC.

Authorizations:
HmacAuth
path Parameters
issuanceId
required
string <uuid>
Request Body schema: application/json
required
txHash
string
rawSignedTransaction
string

Responses

Request samples

Content type
application/json
{
  • "txHash": "string",
  • "rawSignedTransaction": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tokenId": "string",
  • "issuerId": "string",
  • "amount": "string",
  • "destinationAddress": "string",
  • "reference": "string",
  • "metadata": { },
  • "status": "unsigned",
  • "unsignedTransaction": {
    },
  • "txHash": "string",
  • "rawSignedTransaction": "string",
  • "preflight": { },
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Chain RPC

Send an allowlisted JSON-RPC request

Synchronous chain RPC relay for client backends that sign transactions outside Forja. Use it for gas, nonce, call, receipt, and raw transaction broadcast operations. The method allowlist is intentionally narrow.

Authorizations:
HmacAuth
path Parameters
network
required
string (Network)
Enum: "polygon-amoy" "polygon"
Request Body schema: application/json
required
jsonrpc
string
Default: "2.0"
Value: "2.0"
id
string or number or null
method
required
string
Enum: "eth_blockNumber" "eth_call" "eth_estimateGas" "eth_feeHistory" "eth_gasPrice" "eth_getBalance" "eth_getBlockByNumber" "eth_getTransactionByHash" "eth_getTransactionReceipt" "eth_sendRawTransaction"
params
Array of any
Default: []

Responses

Request samples

Content type
application/json
Example
{
  • "jsonrpc": "2.0",
  • "id": "balance-1",
  • "method": "eth_getBalance",
  • "params": [
    ]
}

Response samples

Content type
application/json
{
  • "jsonrpc": "2.0",
  • "id": "string",
  • "result": null
}

Broadcast a raw signed EVM transaction

Broadcasts a raw transaction signed by the client backend EOA and returns the transaction hash.

Authorizations:
HmacAuth
Request Body schema: application/json
required
network
required
string (Network)
Enum: "polygon-amoy" "polygon"
rawSignedTransaction
required
string^0x[a-fA-F0-9]+$

Responses

Request samples

Content type
application/json
{
  • "network": "polygon-amoy",
  • "rawSignedTransaction": "0x02..."
}

Response samples

Content type
application/json
{
  • "txHash": "string"
}

Console Admin

List API keys

Authorizations:
BearerSession

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create API key

Returns the API secret once. Store it immediately.

Authorizations:
BearerSession
Request Body schema: application/json
required
scopes
Array of strings (ApiScope)
Default: ["tokens.read","issuances.read","issuances.create"]
Items Enum: "tokens.read" "issuances.read" "issuances.create"

Responses

Request samples

Content type
application/json
{
  • "scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "apiKey": "string",
  • "issuerId": "string",
  • "scopes": [
    ],
  • "environment": "sandbox",
  • "isActive": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "apiSecret": "string"
}

Enable or disable API key

Authorizations:
BearerSession
path Parameters
apiKey
required
string
Request Body schema: application/json
required
isActive
required
boolean

Responses

Request samples

Content type
application/json
{
  • "isActive": true
}

Response samples

Content type
application/json
{
  • "apiKey": "string",
  • "issuerId": "string",
  • "scopes": [
    ],
  • "environment": "sandbox",
  • "isActive": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

List console users

Authorizations:
BearerSession

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Invite console user

Authorizations:
BearerSession
Request Body schema: application/json
required
email
required
string <email>
role
required
string (ConsoleRole)
Enum: "admin" "operator" "viewer"
requireWebAuthn
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "role": "admin",
  • "requireWebAuthn": false
}

Response samples

Content type
application/json
{
  • "userId": "string",
  • "issuerId": "string",
  • "email": "user@example.com",
  • "role": "admin",
  • "status": "invited",
  • "requireWebAuthn": true,
  • "lastLoginAt": "2019-08-24T14:15:22Z",
  • "invitedBy": "string",
  • "invitedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update console user role/status

Authorizations:
BearerSession
path Parameters
userId
required
string <uuid>
Request Body schema: application/json
required
role
string (ConsoleRole)
Enum: "admin" "operator" "viewer"
status
string
Enum: "invited" "active" "disabled"
requireWebAuthn
boolean

Responses

Request samples

Content type
application/json
{
  • "role": "admin",
  • "status": "invited",
  • "requireWebAuthn": true
}

Response samples

Content type
application/json
{
  • "userId": "string",
  • "issuerId": "string",
  • "email": "user@example.com",
  • "role": "admin",
  • "status": "invited",
  • "requireWebAuthn": true,
  • "lastLoginAt": "2019-08-24T14:15:22Z",
  • "invitedBy": "string",
  • "invitedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Register token for issuer

Authorizations:
BearerSession
Request Body schema: application/json
required
id
string
symbol
required
string
name
required
string
decimals
required
integer [ 0 .. 36 ]
network
required
string (Network)
Enum: "polygon-amoy" "polygon"
contractAddress
required
string^0x[a-fA-F0-9]{40}$
standard
required
string
Enum: "ERC20" "ERC20-upgradeable"
minter
required
string^0x[a-fA-F0-9]{40}$
governanceMode
string
Default: "eoa"
Value: "eoa"

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "symbol": "string",
  • "name": "string",
  • "decimals": 36,
  • "network": "polygon-amoy",
  • "contractAddress": "string",
  • "standard": "ERC20",
  • "minter": "string",
  • "governanceMode": "eoa"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "issuerId": "string",
  • "symbol": "string",
  • "name": "string",
  • "decimals": 0,
  • "network": "polygon-amoy",
  • "contractAddress": "string",
  • "implementationAddress": "string",
  • "standard": "ERC20",
  • "status": "active",
  • "governanceMode": "eoa",
  • "governance": {
    },
  • "mintAuthority": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update token configuration

Authorizations:
BearerSession
path Parameters
tokenId
required
string
Request Body schema: application/json
required
id
string
symbol
required
string
name
required
string
decimals
required
integer [ 0 .. 36 ]
network
required
string (Network)
Enum: "polygon-amoy" "polygon"
contractAddress
required
string^0x[a-fA-F0-9]{40}$
standard
required
string
Enum: "ERC20" "ERC20-upgradeable"
minter
required
string^0x[a-fA-F0-9]{40}$
governanceMode
string
Default: "eoa"
Value: "eoa"

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "symbol": "string",
  • "name": "string",
  • "decimals": 36,
  • "network": "polygon-amoy",
  • "contractAddress": "string",
  • "standard": "ERC20",
  • "minter": "string",
  • "governanceMode": "eoa"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "issuerId": "string",
  • "symbol": "string",
  • "name": "string",
  • "decimals": 0,
  • "network": "polygon-amoy",
  • "contractAddress": "string",
  • "implementationAddress": "string",
  • "standard": "ERC20",
  • "status": "active",
  • "governanceMode": "eoa",
  • "governance": {
    },
  • "mintAuthority": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}