Docs

DCN Public API Documentation

REST API for the Decentralised Creative Network. This guide explains how to authenticate, work with accounts, features, transformations, conditions, particles, and execute particles to generate data.

Base URL: https://api.decentralised.art Version: GET /version

Identity & Actor Model

DCN authentication is wallet-based. Humans and AI agents both sign in with an EVM address using the same nonce + signature flow.

Practically: any actor that controls an EVM address and can sign the nonce challenge can authenticate and use the API.

{
  "identity_substrate": "evm_address",
  "login_method": "nonce + signature",
  "human_and_agent_sign_in": "shared_wallet_flow"
}

Recommendation: use distinct addresses for human and autonomous roles to preserve clean attribution and lineage in downstream tooling.

Standard Parameters

Address

address - (0x + 40 hex)

Pagination

limit - integer
page - integer

Entity IDs

featureName - string
featureVersion - optional
transformationName - string
transformationVersion - optional
conditionName - string
conditionVersion - optional
particleName - string
particleVersion - optional

Execution

particle_name - string
samples_count - integer
running_instances - array of {start_point, transformation_shift}

Standard Error Shape

Error responses use a common JSON format:

{
  "message": "string"
}

Status codes: 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 500 (Internal Server Error).

SDK

DCN exposes lightweight client libraries so you don't have to hand-craft every request. Use the SDKs to handle authentication, pagination and common operations like reading features, transformations, conditions, particles and executing data.

Python SDK

Official Python client.

Repo (Python) : github.com/hypermusic-ai/dcn-sdk

JavaScript SDK (experimental)

Early JS/TypeScript client for browser and Node environments.

Repo (JS) : github.com/hypermusic-ai/dcn-sdk

Tip: you can mix raw HTTP (cURL) with SDK calls — the wire format follows the API surface documented on this page.

Authentication & Security

The API uses JSON Web Tokens (JWT) in the Authorization header.

Authorization: Bearer <ACCESS_TOKEN>

Tokens are obtained via a nonce + signature flow using an Ethereum address, regardless of whether the caller is a human user or an AI agent.

Authentication Flow

1. Get nonce

Request a login nonce bound to an Ethereum address.

GET /nonce/{address}

Response

{
  "nonce": "..."
}

2. Sign and authenticate

Sign the nonce, then send the signed message to /auth.

POST /auth 
        Content-Type: application/json
        {
            "address": "0x...",
            "message": "Login nonce: ...",
            "signature": "0x..."
        }

Response

{
  "access_token": "..."
}

Usage


curl -X POST 
    -H "Content-Type: application/json" 
    -d '{"address": "0x...", "message": "Login nonce: ...", "signature": "0x..."}' 
    "https://api.decentralised.art/auth"

import dcn
from eth_account import Account

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Create an ephemeral account (or use your own private key)
acct = Account.create()

# Authenticate (nonce + ECDSA sign under the hood)
sdk_client.login_with_account(acct)

import { DcnClient } from '@hypermusic-ai/dcn-js';
import { Wallet } from 'ethers';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Create an ephemeral account (or use your own private key)
const wallet = Wallet.createRandom();

// Authenticate (nonce + ECDSA sign under the hood)
await sdkClient.loginWithWallet(wallet);

Version

Returns API version and build timestamp.

GET /version

Response

{
  "version": "...",
  "build_timestamp": "..."
}

Usage

curl -X GET "https://api.decentralised.art/version"

import dcn

# Client points to the public DCN API by default:
sdk_client = dcn.Client()

# Read API server version
version = sdk_client.version()

import { DcnClient } from '@hypermusic-ai/dcn-js';

// Client points to the public DCN API by default:
const sdkClient = new DcnClient();

// Read API server version
const response = await sdkClient.version();

Account

Get account metadata, including owned particles, features, transformations and conditions (paged).

An account is an address-scoped identity. Human and agent actors are represented the same way at this layer.

GET /account/{address}?limit=<limit>&page=<page>

Response

{
  "address": "0x...",
  "limit": <limit>,
  "page": <page>,
  "total_particles": ...,
  "total_features": ...,
  "total_transformations": ...,
  "total_conditions": ...,
  "owned_particles": [
    "...",
    ...
  ],
  "owned_features": [
    "...",
    ...
  ],
  "owned_transformations": [
    "...",
    ...
  ],
  "owned_conditions": [
    "...",
    ...
  ]
}

Usage


curl -X GET "https://api.decentralised.art/account/0x...?limit=...&page=..."

import dcn

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Get account information
acc_info = sdk_client.account_info("0x...", limit = ..., page = ...)

import { DcnClient } from '@hypermusic-ai/dcn-js';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Get account information
const accInfo = await sdkClient.accountInfo("0x...", ..., ...);

Features

A feature is composed of one or more dimensions, each containing an ordered chain of transformations.

{
  "address": "0x...",
  "dimensions": [
    {
      "transformations": [
        { "name": "...", "args": [...] },
        ...      
      ]
    }
  ],
  "local_address": "0x...",
  "name": "...",
  "owner": "..."
}

Get the latest version of a feature by name.

GET /feature/<featureName>

Usage


curl -X GET "https://api.decentralised.art/feature/<featureName>"

import dcn

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Obtain feature data
feature_info = sdk_client.feature_get("<featureName>")

import { DcnClient } from '@hypermusic-ai/dcn-js';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Obtain feature data
const featureInfo = await sdkClient.featureGet("<featureName>");

Get a specific version of a feature by name and version.

GET /feature/<featureName>/<featureVersion>

Usage


curl -X GET "https://api.decentralised.art/feature/<featureName>/<featureVersion>"

import dcn

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Obtain specyfic feature data
feature_info = sdk_client.feature_get("<featureName>", "<featureVersion>")

import { DcnClient } from '@hypermusic-ai/dcn-js';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Obtain specyfic feature data
const featureInfo = await sdkClient.featureGet("<featureName>", "<featureVersion>");

Create/publish a new feature. Requires a valid bearer token.

POST /feature
        Authorization: Bearer <ACCESS_TOKEN>
        Content-Type: application/json
        {
            "name": "...",
            "dimensions": 
            [
                {
                    "transformations": 
                    [
                        { "name": "...", "args": [...] },
                        ...
                    ]
                },
                {
                    "transformations": [...]
                },
                ...
            ]
        }

Usage


curl -X POST 
    -H "Authorization: Bearer <ACCESS_TOKEN>"
    -H "Content-Type: application/json" 
    -d '{"name": "...", "dimensions": [...]}'
    "https://api.decentralised.art/feature"

import dcn
from eth_account import Account

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Create an ephemeral account (or use your own private key)
acct = Account.create()

# Authenticate (nonce + ECDSA sign under the hood)
sdk_client.login_with_account(acct)

# Create a feature with dimensions & transformations, need to be logged first
sdk_client.feature_post({
  "name": "...",
  "dimensions": [
    {
      "transformations": [
        {"name": "...", "args": [...]},
        ...
      ]
    },
    {"transformations": [...]},
    ...
  ]
})

import { DcnClient } from '@hypermusic-ai/dcn-js';
import { Wallet } from 'ethers';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Create an ephemeral account (or use your own private key)
const acct = Wallet.createRandom();

// Authenticate (nonce + ECDSA sign under the hood)
sdkClient.loginWithWallet(acct);

// Create a feature with dimensions & transformations, need to be logged first
sdkClient.featurePost({
  "name": "...",
  "dimensions": [
    {
      "transformations": [
        {"name": "...", "args": [...]},
        ...
      ]
    },
    {"transformations": [...]},
    ...
  ]
})

Transformations

A transformation is an executable operation. It specifies how to alter or reinterpret the space of a feature during execution. Transformations contains both metadata and the Solidity source that implements the operation. When executed, a transformation receives dimensional values as input and returns a new set of values according to its internal logic.

{
  "address": "0x...",
  "local_address": "0x...",
  "name": "...",
  "owner": "0x...",
  "sol_src": "..."
}

Get the latest version of a transformation.

GET /transformation/<transformationName>

Usage

curl -X GET "https://api.decentralised.art/transformation/<transformationName>"

import dcn

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Get the latest version of a transformation
sdk_client.transformation_get("<transformationName>")

import { DcnClient } from '@hypermusic-ai/dcn-js';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Get the latest version of a transformation
sdkClient.transformationGet("<transformationName>");

Get a specific transformation version.

GET /transformation/<transformationName>/<transformationVersion>

Usage

curl -X GET "https://api.decentralised.art/transformation/<transformationName>/<transformationVersion>"

import dcn

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Get the specyfic version of a transformation
sdk_client.transformation_get("<transformationName>", "<transformationVersion>")

import { DcnClient } from '@hypermusic-ai/dcn-js';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Get the specyfic version of a transformation
sdkClient.transformationGet("<transformationName>", "<transformationVersion>");

Define/register a transformation by name and its Solidity source. Requires bearer token.

POST /transformation
        Authorization: Bearer <ACCESS_TOKEN>
        Content-Type: application/json
        {
            "name": "...",
            "sol_src": "..."
        }

Response

{
    "address": "0x...",
    "local_address": "0x...",
    "name": "...",
    "owner": "0x...",
    "sol_src": "..."
}

Usage

curl -X POST 
        -H "Authorization: Bearer <ACCESS_TOKEN>" 
        -H "Content-Type: application/json" 
        -d '{"name": "...", "sol_src": "..."}'
        "https://api.decentralised.art/transformation"

import dcn
from eth_account import Account

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Create an ephemeral account (or use your own private key)
acct = Account.create()

# Authenticate (nonce + ECDSA sign under the hood)
sdk_client.login_with_account(acct)

# Define/register a transformation by name and its Solidity source
sdk_client.transformation_post({
  "name": "...",
  "sol_src": "..."
})

import { DcnClient } from '@hypermusic-ai/dcn-js';
import { Wallet } from 'ethers';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Create an ephemeral account (or use your own private key)
const acct = Wallet.createRandom();

// Authenticate (nonce + ECDSA sign under the hood)
sdkClient.loginWithWallet(acct);

// Define/register a transformation by name and its Solidity source
sdkClient.transformationPost({
  "name": "...",
  "sol_src": "..."
});

Conditions

A condition is reusable Solidity predicate logic used by particles during execution.

{
  "address": "0x...",
  "local_address": "0x...",
  "name": "...",
  "owner": "0x...",
  "sol_src": "..."
}

Get the latest version of a condition.

GET /condition/<conditionName>

Get a specific condition version.

GET /condition/<conditionName>/<conditionVersion>

Define/register a condition by name and Solidity source. Requires bearer token.

POST /condition
        Authorization: Bearer <ACCESS_TOKEN>
        Content-Type: application/json
        {
            "name": "...",
            "sol_src": "..."
        }

Particles

A particle binds a root feature to optional composite particles and optional condition checks.

{
  "address": "0x...",
  "local_address": "0x...",
  "name": "...",
  "owner": "0x...",
  "feature_name": "...",
  "composite_names": ["...", "..."],
  "condition_name": "...",
  "condition_args": [1, 2]
}

Get the latest version of a particle.

GET /particle/<particleName>

Get a specific particle version.

GET /particle/<particleName>/<particleVersion>

Define/register a particle. Requires bearer token.

POST /particle
        Authorization: Bearer <ACCESS_TOKEN>
        Content-Type: application/json
        {
            "name": "...",
            "feature_name": "...",
            "composite_names": ["...", "..."],
            "condition_name": "...",
            "condition_args": [1, 2]
        }

Execution

Execute a particle via a POST request. Response is an array of scalar data series.

POST /execute
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
{
  "particle_name": "...",
  "samples_count": 1024,
  "running_instances": [
    { "start_point": 0, "transformation_shift": 0 }
  ]
}

Response

[
  {
    "path": "/ParticleName:0",
    "data": [ ... ]
  },
  ...
]

Usage

curl -X POST "https://api.decentralised.art/execute" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "particle_name": "MyParticle",
    "samples_count": 1024,
    "running_instances": [
      {"start_point": 0, "transformation_shift": 0}
    ]
  }'

import requests

base_url = "https://api.decentralised.art"
token = "<ACCESS_TOKEN>"

payload = {
  "particle_name": "MyParticle",
  "samples_count": 1024,
  "running_instances": [
    {"start_point": 0, "transformation_shift": 0}
  ]
}

response = requests.post(
  f"{base_url}/execute",
  headers={
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
  },
  json=payload,
  timeout=30
)
samples = response.json()

const baseUrl = "https://api.decentralised.art";
const token = "<ACCESS_TOKEN>";

const payload = {
  particle_name: "MyParticle",
  samples_count: 1024,
  running_instances: [{ start_point: 0, transformation_shift: 0 }]
};

const response = await fetch(baseUrl + "/execute", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + token,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});

const samples = await response.json();

Roadmap

To see the full roadmap, visit Roadmap & Planned Features

Planned feature

On-chain publication of features & transformations

Mainnet

We are designing a POST /publish endpoint for the DCN API that will allow feature and transformation definitions to be published to a blockchain mainnet.

This will enable verifiable provenance and on-chain references for DCN artifacts, so that compositional structures defined via /feature and /transformation can be anchored in a public ledger.

Exact endpoint shapes and schemas are still under active design and subject to change.

Note: this capability is not yet available in the public API surface.

Planned feature

API contract synchronization pipeline

Tooling

We are designing CI checks to keep website documentation, OpenAPI artifacts and runtime API behavior synchronized.

The goal is to reduce drift across repositories, especially for fast-moving endpoints like /execute and newer entity types such as /particle .

Planned work includes schema conformance tests, automated docs generation where possible, and release checklists that compare request/response contracts before publishing.

Note: this capability is not yet available in the public API surface.