Yellow endpoints

Private-channel API surface and current implementation boundaries

Create private channel

Build stealth channel metadata and publish announcement-linked channel ids.

Discover channels

Scan existing announcements for channel-specific discoveries.

Read config

Inspect Yellow ws/contract config exposed by backend.

Current Yellow endpoints are integration scaffolding. Several responses are placeholders and do not submit real L1 settlement transactions.

Endpoint list

• POST /api/v1/yellow/channel/create
• POST /api/v1/yellow/channel/discover
• POST /api/v1/yellow/channel/fund
• POST /api/v1/yellow/channel/close
• GET /api/v1/yellow/channel/:id/status
• POST /api/v1/yellow/transfer
• GET /api/v1/yellow/config

Integration path

1. Create channel announcement

   Call /api/v1/yellow/channel/create with recipient, token, and amount.

2. Discover as recipient

   Call /api/v1/yellow/channel/discover with recipient key material.

3. Inspect and progress state

   Read status/config and optionally call fund, transfer, and close endpoints.

Endpoint schemas

POST /api/v1/yellow/channel/create

recipient · string · required

Recipient ENS name ending in .eth or a hex meta-address string.

token · string · required

Token identifier string (currently logged but not enforced in backend channel state).

amount · string · required

Initial funding amount as string.

channel_id · string

Optional 32-byte channel id hex. If omitted, backend generates random id.

channel_id · string · required

Response channel id.

stealth_address · string · required

Recipient stealth EVM address.

announcement · object · required

Announcement payload for channel discovery.

ephemeral_key · string · required

Hex ciphertext.

view_tag · integer · required

View tag byte.

channel_id · string · required

Channel identifier.

tx_hash · string · required

Synthetic hash-like value derived in handler.

POST /api/v1/yellow/channel/discover

viewing_sk · string · required

Viewing secret key in hex.

spending_pk · string · required

Spending public key in hex.

spending_sk · string · required

Spending secret key in hex.

channels · array · required

Discovered channel rows.

POST /api/v1/yellow/channel/fund

channel_id · string · required

Channel id string.

amount · string · required

Amount string.

tx_hash · string · required

Placeholder tx-like value.

new_balance · string · required

Echoed amount from request.

POST /api/v1/yellow/channel/close

channel_id · string · required

Channel id string.

tx_hash · string · required

Placeholder tx-like value.

tx_hash_is_placeholder · boolean · required

Always true in current backend close handler.

final_balances · array · required

Final allocations returned by backend.

GET /api/v1/yellow/channel/:id/status

id · string · required

Channel id path parameter.

channel_id · string · required

Channel id echoed in response.

status · string · required

open when announcement exists, otherwise unknown.

balances · array · required

Current balance entries.

participants · array · required

Participants list (empty in current implementation).

created_at · integer · required

Timestamp from matching announcement or 0.

version · integer · required

Static state version (1 currently).

POST /api/v1/yellow/transfer

channel_id · string · required

Channel id string.

destination · string · required

Transfer destination.

amount · string · required

Amount to transfer.

asset · string · required

Asset identifier.

new_state_version · integer · required

Static value 2 in current implementation.

balances · array · required

Updated balances array.

GET /api/v1/yellow/config

ws_url · string · required

Yellow websocket endpoint.

custody_address · string · required

Configured custody contract address.

adjudicator_address · string · required

Configured adjudicator contract address.

chain_id · integer · required

Configured chain id.

supported_tokens · array · required

Hardcoded token metadata list (currently USDC and ETH entries).

Example calls

Create channel

curl -s -X POST http://localhost:3001/api/v1/yellow/channel/create \
  -H "Content-Type: application/json" \
  -d '{
    "recipient":"bob.eth",
    "token":"USDC",
    "amount":"1000"
  }' | jq .

Discover channels

curl -s -X POST http://localhost:3001/api/v1/yellow/channel/discover \
  -H "Content-Type: application/json" \
  -d '{
    "viewing_sk":"<HEX_VIEWING_SK>",
    "spending_pk":"<HEX_SPENDING_PK>",
    "spending_sk":"<HEX_SPENDING_SK>"
  }' | jq .

Read config

curl -s http://localhost:3001/api/v1/yellow/config | jq .

Implementation caveats

Placeholder transaction fields

Fund and close handlers return placeholder tx-like values. Close also marks tx_hash_is_placeholder: true.

Token handling simplification

Discovery/status responses currently use simplified token behavior and do not represent full custody settlement logic.

No backend L1 close submission

Close handler does not submit an L1 transaction; settlement is expected from Yellow Network processing outside this backend.