The Wallco Agent API

1. Who qualifies

An agent is an AI-driven autonomous actor (Claude, GPT, custom LLM workflows, headless scripts orchestrated by an LLM) that performs marketplace actions on behalf of a human designer, studio, or brand. Examples:

• A designer's own Claude session that uploads new patterns, auto-tags them, generates colorways, and answers license inquiries.
• A studio's MCP server that mirrors a Figma library into Wallco and keeps the storefront in sync.
• A brand's automation that converts approved exclusive licenses into Shopify SKUs and watches the commission ledger.

To qualify, the agent must:

• Be tied to a single verified mp_designer_profile. No anonymous traffic.
• Accept the same rights warranty per asset as a human uploader (you own or control all rights, you grant Wallco the rights in the designer agreement).
• Pass manual review on first 3 patterns. After that, the designer can opt into auto-approval for that agent.
• Have a signed agent-of-record agreement on file (a one-line attestation in the application body is enough — see §5).

2. Hard rules — what gets blocked

3. Authentication

Wallco uses a signed HMAC cookie called mp_designer. The cookie is issued by POST /api/marketplace/designer/apply and is valid for 30 days. Treat it like a bearer token — keep it secret, rotate by re-applying.

For headless agents, capture the Set-Cookie header on the apply response and replay it on every subsequent call as a Cookie header.

curl -sS -i -X POST https://wallco.ai/api/marketplace/designer/apply \
  -H 'content-type: application/json' \
  -d '{
    "display_name": "Astrid Mauve Studio",
    "email": "astrid@example.com",
    "rights_agreement": true,
    "studio_name": "Astrid Mauve Studio",
    "bio": "Brooklyn-based pattern designer specializing in botanical maximalism. Agent-of-record: a Claude session managed by astrid@example.com.",
    "style_tags": ["Botanical","Maximalist"]
  }' | grep -i set-cookie
# Set-Cookie: mp_designer=AbC...Xyz.dEf...; Path=/; Max-Age=2592000; SameSite=Lax; HttpOnly

Replay the cookie on every authenticated call:

curl -sS https://wallco.ai/api/marketplace/designer/me \
  -H "cookie: mp_designer=AbC...Xyz.dEf..."

4. Base URL · versioning

• Production: https://wallco.ai
• Local dev: http://127.0.0.1:9792
• Versioning: v1, implicit (no /v1/ prefix yet). Breaking changes will move under /api/marketplace/v2/ and be announced 30 days in advance.
• Content types: JSON in/out (application/json) except POST /patterns/upload which is multipart/form-data.

5. Onboarding endpoints

6. Profile endpoints

7. Pattern endpoints

8. AI helper endpoints

Three live-LLM endpoints. The tag + copy endpoints run on Mac1 qwen3:14b (~30–90s/call). The colorways endpoint runs on Gemini 2.5 Flash Image (~5–15s/call × 6 in parallel).

9. Licensing endpoints

10. Commission endpoints

11. Project / trade endpoints

12. Discovery endpoints

13. Status / health

14. Errors

All errors return JSON of the shape:

{ "error": "<short human-readable message>" }

• 400 — malformed body, missing required field, bad pattern_slug.
• 401 — designer cookie missing or expired.
• 403 — admin endpoint hit without admin auth, or designer account suspended/rejected.
• 404 — resource not found, or endpoint is admin-gated and you're not admin (intentional 404, not 401).
• 413 — body too large.
• 500 — server error. Retry with exponential backoff; if it persists, contact marketplace@wallco.ai.

15. Rate limits

• Read endpoints: 120 req / minute / cookie or IP (whichever is higher).
• Write endpoints (apply, upload, inquiry): 30 req / minute / cookie. Patterns: max 50 uploads / 24h / designer.
• LLM endpoints (tag, write, colorways): 6 concurrent calls / cookie. Each call takes 5–90s; queue accordingly.
• Backoff: 429 responses include Retry-After in seconds. Honor it.

16. End-to-end examples

Apply, upload, auto-tag, auto-copy, auto-colorway (Node.js)

import fs from 'node:fs';

const BASE = 'https://wallco.ai';
let COOKIE = '';

async function api(path, opts = {}) {
  const headers = { 'content-type': 'application/json', ...opts.headers };
  if (COOKIE) headers.cookie = COOKIE;
  const res = await fetch(BASE + path, { ...opts, headers });
  const setCookie = res.headers.get('set-cookie');
  if (setCookie && setCookie.includes('mp_designer=')) {
    COOKIE = setCookie.split(';')[0];
  }
  if (!res.ok) throw new Error(`${res.status} ${path}: ${await res.text()}`);
  return res.json();
}

// 1. Onboard (one-time per agent)
const apply = await api('/api/marketplace/designer/apply', {
  method: 'POST',
  body: JSON.stringify({
    display_name: 'Astrid Mauve Studio',
    email: 'astrid@example.com',
    rights_agreement: true,
    bio: 'Brooklyn-based pattern designer specializing in botanical maximalism. ' +
         'Agent-of-record: a Claude session managed by astrid@example.com.',
    style_tags: ['Botanical', 'Maximalist'],
  }),
});
// → { ok: true, designer: { id, slug, status: 'pending' } }

// 2. Upload a pattern (multipart — use FormData)
const fd = new FormData();
fd.append('image', new Blob([fs.readFileSync('./wildflower-reverie.png')]), 'wildflower-reverie.png');
fd.append('title', 'Wildflower Reverie');
fd.append('rights_warranty', 'true');
fd.append('repeat_type', 'half-drop');
fd.append('scale_notes', 'large repeat ~30in');
const upload = await fetch(BASE + '/api/marketplace/patterns/upload', {
  method: 'POST', headers: { cookie: COOKIE }, body: fd,
}).then(r => r.json());
const slug = upload.pattern.slug;

// 3. Let qwen3:14b tag it (persists tags into mp_patterns)
await api('/api/marketplace/ai/tag-pattern', {
  method: 'POST',
  body: JSON.stringify({ patternSlug: slug }),
});

// 4. Let qwen3:14b write the copy
await api('/api/marketplace/ai/write-pattern-description', {
  method: 'POST',
  body: JSON.stringify({ patternSlug: slug }),
});

// 5. Generate 6 colorways via Gemini
await api('/api/marketplace/ai/generate-colorways', {
  method: 'POST',
  body: JSON.stringify({ patternSlug: slug }),
});

// 6. Wait for admin to approve, then poll commission ledger
const me = await api('/api/marketplace/designer/me');
console.log('points:', me.designer.points, 'commission rows:', me.commission_ledger.length);

Same flow in Python

import requests, json

BASE = 'https://wallco.ai'
s = requests.Session()

# 1. Onboard
r = s.post(f'{BASE}/api/marketplace/designer/apply', json={
    'display_name': 'Astrid Mauve Studio',
    'email': 'astrid@example.com',
    'rights_agreement': True,
    'bio': 'Brooklyn-based pattern designer. Agent-of-record: a Python script run by astrid@example.com.',
    'style_tags': ['Botanical', 'Maximalist'],
})
r.raise_for_status()
# session.cookies now contains mp_designer automatically

# 2. Upload a pattern
with open('wildflower-reverie.png', 'rb') as f:
    r = s.post(f'{BASE}/api/marketplace/patterns/upload',
        files={'image': ('wildflower-reverie.png', f, 'image/png')},
        data={
            'title': 'Wildflower Reverie',
            'rights_warranty': 'true',
            'repeat_type': 'half-drop',
            'scale_notes': 'large repeat ~30in',
        })
r.raise_for_status()
slug = r.json()['pattern']['slug']

# 3. Auto-tag
s.post(f'{BASE}/api/marketplace/ai/tag-pattern',  json={'patternSlug': slug}).raise_for_status()
# 4. Auto-copy
s.post(f'{BASE}/api/marketplace/ai/write-pattern-description', json={'patternSlug': slug}).raise_for_status()
# 5. Colorways
s.post(f'{BASE}/api/marketplace/ai/generate-colorways', json={'patternSlug': slug}).raise_for_status()

# 6. Read commission ledger
print(s.get(f'{BASE}/api/marketplace/commissions/ledger').json())

17. Terms for agents

By using this API on behalf of a designer, the agent's operator agrees that:

• The designer retains full liability for every uploaded asset's rights and warranty. The agent is a tool, not a legal shield.
• Wallco may suspend the mp_designer cookie at any time without notice if abuse is detected.
• All API responses may be cached for up to 60s on the edge; do not rely on real-time round-trip consistency.
• Agent traffic is logged with cookie ID, IP, and User-Agent for fraud review. Use a distinctive User-Agent (e.g. AstridMauveAgent/0.3 (claude-sonnet-4-6)) so support can identify your traffic when reaching out.
• This page is the authoritative spec. The accompanying source of truth is src/marketplace/index.js in the wallco-ai repo — if the page and the code disagree, the code wins until the page is corrected.

Questions, scope expansion, agent-of-record agreements: marketplace@wallco.ai. Last updated 2026-05-13.