Build on Ichiba

What is a seeder?

A market seeder is a one-shot CLI program that syncs your cloud provider's catalog into the Ichiba marketplace. It runs to completion — fetching, mapping, and upserting listings — then exits. You schedule it as a cron job (hourly, daily, etc.) to keep pricing and availability current.

Prerequisites

• An Ichiba API token — generate one from your organization's API Tokens section in the web app
• Cloud provider credentials appropriate for reading instance type or pricing data (e.g. AWS credentials via the standard SDK credential chain, a DigitalOcean personal access token, a Hetzner API token)
• Network access to both the provider's API and https://api.ichiba.tech

How it works

A seeder follows this sequence on every run:

1. Read configuration — load ICHIBA_API_TOKEN, ICHIBA_API_URL, and provider credentials from environment variables.
2. Fetch existing listings — call GET /api/listings with your Bearer token and build a name → listing ID map so you can update existing entries instead of creating duplicates.
3. Query the provider — call the cloud provider's API to get the current set of available instance types, storage classes, and their prices.
4. Map to Ichiba payload — transform each provider offering into an Ichiba listing payload (see the schema below).
5. Upsert — if the listing name already exists in your name → ID map, call PUT /api/listings/{id} to update it. Otherwise call POST /api/listings to create it.
6. Print summary — report the count of created, updated, skipped, and failed listings.

The listing payload

The API reference documents the full schema. Below are representative payloads for the two asset types.

Compute listing

{
  "listing": {
    "name": "m6i.xlarge",
    "description": "General-purpose — 4 vCPU, 16 GB RAM",
    "asset_type": "compute",
    "price": "0.192",
    "status": "active"
  },
  "instance_type_spec": {
    "family": "general",
    "vcpus": 4,
    "memory_gb": "16",
    "cpu_architecture": "x86_64",
    "network_gbps": "12.5",
    "region": "us-east-1"
  },
  "network_spec": {
    "ipv4_included": true,
    "ipv6_supported": true,
    "byoip_supported": false,
    "private_networking": true,
    "egress_price_per_gb": "0.09"
  }
}

Block storage listing

{
  "listing": {
    "name": "Standard Block Storage — nyc3",
    "description": "SSD-backed block storage, multi-region replicated",
    "asset_type": "block_storage",
    "price": "0.10",
    "status": "active"
  },
  "block_storage_spec": {
    "capacity_gb": "500",
    "storage_class": "standard",
    "redundancy": "multi_region",
    "max_iops": 10000,
    "max_throughput_mbps": "500",
    "region": "nyc3"
  }
}

Set status to draft if you want to review listings before making them visible to buyers. Change to active to publish.

Code walkthrough — fetch → map → upsert

The following pseudocode illustrates the core seeder loop. Adapt it to your language and cloud provider SDK of choice.

Step 1 — fetch existing listings

curl https://api.ichiba.tech/api/listings \

  -H "Authorization: Bearer $ICHIBA_API_TOKEN"

Build a map of name → id from the response. You'll use this to decide whether to POST or PUT each offering.

Step 2 — upsert loop

for each offering from provider API:
    payload = map_to_ichiba_payload(offering)

    if existing_id = name_to_id[payload.listing.name]:
        PUT /api/listings/{existing_id}  body=payload
    else:
        POST /api/listings               body=payload

Step 3 — handle errors per listing

if response.status == 201 or 200:
    created_or_updated += 1
elif response.status == 422:
    log("validation error", response.body)
    failed += 1
else:
    log("unexpected status", response.status)
    failed += 1

Running as a cron job

Seeders are designed to be run repeatedly. Because each run is idempotent (it upserts by name), you can schedule it as often as needed without creating duplicate listings.

Build and run (Go example)

go build -o seeder . && ./seeder

Crontab entry — run daily at midnight

0 0 * * * /opt/seeder/seeder >> /var/log/seeder.log 2>&1

Docker

docker build -t my-seeder .

docker run --env-file .env my-seeder

Pass ICHIBA_API_TOKEN, ICHIBA_API_URL, and provider credentials via environment variables or an env file. Never bake secrets into the image.

What is a gateway?

A seller gateway is a persistent HTTP service that you operate. It implements a small, well-defined API that Ichiba calls to provision and deprovision cloud resources on behalf of buyers. Your gateway handles the cloud-provider-specific logic; Ichiba handles billing, discovery, and the buyer experience.

Prerequisites

• A publicly routable HTTPS endpoint for your gateway service
• A shared secret you choose — set as ICHIBA_GATEWAY_SECRET and registered in your Ichiba seller profile
• A PostgreSQL database to persist tenant state and credentials
• Cloud provider credentials with permission to create, describe, and delete the resources you are selling
• An encryption key for storing access credentials at rest — set as GATEWAY_ENCRYPTION_KEY

The HTTP API contract

All gateways must implement these four endpoints. Ichiba will not call any others.

{ "status": "ok" }

{
  "idempotency_key": "purchase_550e8400-e29b-41d4-a716-446655440000",
  "listing_id": 42,
  "buyer_org_id": 7,
  "asset_type": "compute",
  "spec": {
    "vcpus": 4,
    "memory_gb": "16",
    "region": "us-east-1"
  }
}

{
  "id": "tenant_abc123",
  "status": "active",
  "access_details": {
    "host": "ec2-203-0-113-42.compute-1.amazonaws.com",
    "username": "ubuntu",
    "ssh_private_key": "-----BEGIN RSA PRIVATE KEY-----\n..."
  }
}

{
  "id": "tenant_def456",
  "status": "active",
  "access_details": {
    "volume_id": "vol-0abcdef1234567890",
    "region": "us-east-1",
    "device": "/dev/xvdf"
  }
}

{
  "id": "tenant_ghi789",
  "status": "provisioning",
  "access_details": null
}

{
  "id": "tenant_abc123",
  "status": "active",
  "access_details": { ... }
}

{ "id": "tenant_abc123", "status": "cancelled" }

The tenant lifecycle

Each tenant moves through a well-defined set of states:

The normal path is provisioning → active → cancelled. If creation fails, transition to failed with an error message. Retain the tenant row in your database after cancellation — delete only the cloud resource.

Step-by-step implementation

curl https://your-gateway.example.com/tenants \

  -X POST \

  -H "Authorization: Bearer $ICHIBA_GATEWAY_SECRET" \

  -H "Content-Type: application/json" \

  -d '{"idempotency_key":"k1","listing_id":42,...}'

existing = db.find_tenant_by_idempotency_key(params.idempotency_key)
if existing:
    return 200, existing

tenant = db.create_tenant(idempotency_key=params.idempotency_key, status="provisioning")
resource = cloud.create_resource(params.spec)
tenant.update(status="active", access_details=encrypt(resource.credentials))
return 201, tenant

{
  "ManagedBy":          "ichiba",
  "IchibaListingId":    "42",
  "IchibaBuyerOrgId":   "7",
  "IchibaTenantId":     "tenant_abc123"
}

Configuration & env vars

Registering with Ichiba

Once your gateway is deployed and passes the local lifecycle test, register it in Ichiba so the platform can route purchases to it.

1. Open the web app and navigate to your organization's seller settings.
2. Enter your gateway's public HTTPS URL (e.g. https://gateway.yourcompany.com).
3. Enter the shared secret you configured as ICHIBA_GATEWAY_SECRET.
4. Save. Ichiba will immediately call GET /health to verify connectivity.
5. Activate any listings you want buyers to be able to purchase — they are now backed by your gateway.