Projects API

Base URL: https://api.inkdprotocol.com

Read operations are free. Write operations require x402 payment in USDC.

List projects

GET /v1/projects

Returns all public projects. Free, no authentication required.

Query parameters

Parameter	Type	Default	Description
`offset`	`number`	`0`	Pagination offset
`limit`	`number`	`20`	Results per page (max `100`)

Response 200 OK

{
  "data": [
    {
      "id": "9",
      "name": "my-agent",
      "description": "An autonomous agent",
      "license": "MIT",
      "owner": "0x210bDf52ad7afE3Ea7C67323eDcCD699598983C0",
      "isPublic": true,
      "isAgent": true,
      "agentEndpoint": "https://my-agent.example.com",
      "createdAt": "1741383600",
      "versionCount": "2"
    }
  ],
  "total": 9,
  "offset": 0,
  "limit": 20
}

Get project

GET /v1/projects/:id

Response 200 OK

{
  "id": "9",
  "name": "my-agent",
  "description": "An autonomous agent",
  "license": "MIT",
  "owner": "0x210bDf52ad7afE3Ea7C67323eDcCD699598983C0",
  "isPublic": true,
  "isAgent": true,
  "agentEndpoint": "https://my-agent.example.com",
  "createdAt": "1741383600",
  "versionCount": "2"
}

Errors

Status	Error	Description
`404`	`project_not_found`	No project with that ID

Create project

POST /v1/projects

Registers a new project on-chain. Requires x402 payment.

Cost: $0.10 USDC (minimum, dynamic)

Request body

{
  "name":          "my-agent",
  "description":   "An autonomous agent that manages deployments",
  "license":       "MIT",
  "isPublic":      true,
  "isAgent":       true,
  "agentEndpoint": "https://my-agent.example.com",
  "readmeHash":    "ar://QmReadme..."
}

Field	Type	Required	Constraints	Description
`name`	`string`	✅	Max 64 chars, unique	Project name (normalized to lowercase)
`description`	`string`	—	Max 1024 chars	Short description
`license`	`string`	—	—	SPDX license identifier (default: `MIT`)
`isPublic`	`boolean`	—	—	Default: `true`
`isAgent`	`boolean`	—	—	Mark as an AI agent project
`agentEndpoint`	`string`	—	—	HTTP endpoint for the agent
`readmeHash`	`string`	—	`ar://` prefix	Arweave hash of README content

Response 201 Created

{
  "txHash":    "0x25642785bb06de399e102e3e943c6e93572fb8b65d3c9cceee45a3e430e413b9",
  "projectId": "10",
  "name":      "my-agent",
  "owner":     "0xYourWallet",
  "status":    "success",
  "blockNumber": "25841234"
}

Errors

Status	Error	Description
`400`	`name_required`	`name` field is missing
`400`	`name_too_long`	Name exceeds 64 characters
`400`	`name_taken`	A project with this name already exists
`402`	—	Payment required (x402 flow)

List versions

GET /v1/projects/:id/versions

Returns all versions for a project. Free.

Response 200 OK

{
  "data": [
    {
      "index":       "0",
      "projectId":   "9",
      "arweaveHash": "ar://QmAbc123xyz...",
      "versionTag":  "v1.0.0",
      "changelog":   "Initial release",
      "pushedBy":    "0x210bDf52ad7afE3Ea7C67323eDcCD699598983C0",
      "pushedAt":    "1741383900"
    }
  ]
}

Get version

GET /v1/projects/:id/versions/:index

Returns a specific version by its index (0-based).

Push version

POST /v1/projects/:id/versions

Uploads content to Arweave (if file provided) and records the Arweave hash on-chain. Requires x402 payment.

Cost: Arweave storage cost + 20% markup (min $0.10 USDC). Use the estimate endpoint to get the exact amount before paying.

Request body

{
  "arweaveHash":  "ar://QmAbc123xyz...",
  "versionTag":   "v1.0.0",
  "changelog":    "Add support for streaming responses",
  "contentSize":  14336
}

Field	Type	Required	Description
`arweaveHash`	`string`	✅	Permanent `ar://` content hash. Use `/v1/upload` first if you have a local file.
`versionTag`	`string`	✅	Version identifier (e.g. `v1.0.0`)
`changelog`	`string`	—	Description of changes
`contentSize`	`number`	—	File size in bytes (used for fee display)

Response 201 Created

{
  "txHash":      "0x7a63bd374bd439a73f9090ac8431cbb338bc4693574e7663f6f7aff595eadf18",
  "projectId":   "9",
  "versionIndex": "1",
  "versionTag":  "v1.0.0",
  "arweaveHash": "ar://QmAbc123xyz...",
  "arweaveUrl":  "https://arweave.net/QmAbc123xyz",
  "pusher":      "0xYourWallet",
  "status":      "success",
  "blockNumber": "25841300"
}

Errors

Status	Error	Description
`400`	`hash_required`	`arweaveHash` is missing or empty
`400`	`tag_required`	`versionTag` is missing or empty
`403`	`not_owner_or_collaborator`	Caller is not the project owner or a collaborator
`404`	`project_not_found`	No project with that ID
`402`	—	Payment required (x402 flow)

Estimate version cost

GET /v1/projects/estimate?bytes=102400

Returns the USDC cost to push a version for a given file size.

Query parameters

Parameter	Type	Description
`bytes`	`number`	File size in bytes

Response 200 OK

{
  "bytes":        102400,
  "arweaveCost":  "4600",
  "markup":       "920",
  "total":        "5520",
  "totalUsd":     "$0.0055"
}

All USDC values use 6 decimals. Divide by 1e6 for USD.